@foundation0/git 1.3.0 → 1.3.1

package/src/git-service-api.ts

@@ -1,754 +1,822 @@
-import { createGitPlatformAdapter, type GitPlatformAdapterFactoryDeps } from './platform'
-import { getGitPlatformConfig, type GitPlatformConfig } from './platform/config'
-import { type GitServiceFlag, type GitServiceFeature, gitServiceFeatureSpec } from './git-service-feature-spec.generated'
-import { type GitApiFeatureMapping } from './platform/gitea-adapter'
-import { attachGitLabelManagementApi } from './label-management'
-import { attachGitActionsApi } from './actions-api'
-import { attachGitCiApi } from './ci-api'
-import { spawn } from 'node:child_process'
-import crypto from 'node:crypto'
-
-export interface GitServiceApiFactoryOptions {
-  config?: Partial<GitPlatformConfig>
-  defaultOwner?: string
-  defaultRepo?: string
-  swaggerSpec?: GitPlatformAdapterFactoryDeps['swaggerSpec']
-  requestTimeoutMs?: number
-  httpTransport?: 'fetch' | 'curl'
-  log?: (message: string) => void
-}
-
-export interface GitServiceApiExecutionResult<T = unknown> {
-  mapping: GitApiFeatureMapping
-  request: {
-    url: string
-    method: string
-    headers: Record<string, string>
-    query: string[]
-    body?: unknown
-  }
-  response: {
-    headers: Record<string, string>
-  }
-  status: number
-  ok: boolean
-  body: T
-}
-
-export type GitServiceApiMethod = (...args: unknown[]) => Promise<GitServiceApiExecutionResult>
-
-export type GitServiceApi = {
-  [key: string]: GitServiceApi | GitServiceApiMethod
-}
-
-type ApiCallOptions = {
-  method?: string
-  requestBody?: unknown
-  requestJson?: unknown
-  requestData?: unknown
-  requestPayload?: unknown
-  json?: unknown
-  data?: unknown
-  payload?: unknown
-  headers?: Record<string, string>
-  query?: Record<string, string | number | boolean>
-}
-
-interface NormalizedCall {
-  args: string[]
-  options: Record<string, unknown>
-}
-
-const DEFAULT_REQUEST_TIMEOUT_MS = 60_000
-
-const isPlainObject = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
-const parseRequestTimeoutMs = (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 resolveDefaultRequestTimeoutMs = (): number => {
-  const fromEnv =
-    parseRequestTimeoutMs(process.env.EXAMPLE_GIT_REQUEST_TIMEOUT_MS) ??
-    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_REQUEST_TIMEOUT_MS) ??
-    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_TIMEOUT_MS)
-
-  return fromEnv ?? DEFAULT_REQUEST_TIMEOUT_MS
-}
-
-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 splitArgsAndOptions = (rawArgs: unknown[]): NormalizedCall => {
-  if (rawArgs.length === 0 || !isPlainObject(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 normalizeFlagLookup = (name: string): string =>
-  name.replace(/^--/, '').trim().toLowerCase()
-
-const mapFlagValues = (
-  feature: GitServiceFeature,
-  options: Record<string, unknown>,
-): {
-  flags: Record<string, string | boolean>
-  unhandled: Record<string, unknown>
-} => {
-  const flags: Record<string, string | boolean> = {}
-  const unhandled: Record<string, unknown> = {}
-  const alias = new Map<string, string>()
-
-  for (const flag of feature.flags) {
-    const canonical = normalizeFlagLookup(flag.name)
-    alias.set(canonical, flag.name)
-  }
-
-  const reserved = new Set([
-    'json',
-    'data',
-    'payload',
-    'headers',
-    'query',
-    'method',
-    'requestbody',
-    'requestjson',
-    'requestdata',
-    'requestpayload',
-  ])
-
-  for (const [key, value] of Object.entries(options)) {
-    const normalizedKey = normalizeFlagLookup(key)
-
-    if (value === undefined) {
-      continue
-    }
-
-    if (reserved.has(normalizedKey)) {
-      continue
-    }
-
-    if (alias.has(normalizedKey)) {
-      const canonical = alias.get(normalizedKey)
-      if (canonical) {
-        flags[canonical] = typeof value === 'boolean' ? value : String(value)
-      }
-      continue
-    }
-
-    unhandled[key] = value
-  }
-
-  return { flags, unhandled }
-}
-
-const buildRequestBody = (
-  method: string,
-  options: Record<string, unknown>,
-  defaultBody: Record<string, unknown>,
-): unknown | undefined => {
-  const normalizedMethod = method.toUpperCase()
-  const explicit =
-    options.requestBody ??
-    options.requestJson ??
-    options.requestData ??
-    options.requestPayload ??
-    options.json ??
-    options.data ??
-    options.payload
-
-  if (explicit !== undefined) {
-    return explicit
-  }
-
-  if (!['POST', 'PUT', 'PATCH'].includes(normalizedMethod)) {
-    return undefined
-  }
-
-  if (Object.keys(defaultBody).length > 0) {
-    return defaultBody
-  }
-
-  return undefined
-}
-
-const buildUrl = (
-  apiBase: string,
-  mappedPath: string[],
-  query: string[],
-  additionalQuery: Record<string, string | number | boolean> = {},
-): string => {
-  const path = `${apiBase}/${mappedPath.join('/')}`
-  const url = new URL(path)
-
-  for (const queryPair of query) {
-    const [name, value = ''] = queryPair.split('=', 2)
-    if (!name) {
-      continue
-    }
-
-    url.searchParams.set(name, value)
-  }
-
-  for (const [name, value] of Object.entries(additionalQuery)) {
-    url.searchParams.set(name, String(value))
-  }
-
-  return url.toString()
-}
-
-const unresolvedPathParamPattern = /^\{[^{}]+\}$/
-
-const assertResolvedMappedPath = (
-  mappedPath: string[],
-  featurePath: string[],
-): void => {
-  const unresolved = mappedPath.filter((segment) => unresolvedPathParamPattern.test(segment))
-  if (unresolved.length === 0) {
-    return
-  }
-
-  throw new Error(
-    `Missing required path arguments for "${featurePath.join('.')}". Unresolved parameters: ${unresolved.join(', ')}`,
-  )
-}
-
-const canUseAbortSignalTimeout = (): boolean =>
-  typeof AbortSignal !== 'undefined' && typeof (AbortSignal as unknown as { timeout?: unknown }).timeout === 'function'
-
-const isTestRuntime = (): boolean =>
-  Boolean(process.env.VITEST) || process.env.NODE_ENV === 'test'
-
-const toQueryRecord = (raw: Record<string, unknown>): Record<string, string | number | boolean> => {
-  const query: Record<string, string | number | boolean> = {}
-  for (const [key, value] of Object.entries(raw)) {
-    if (typeof value === 'string') {
-      query[key] = value
-      continue
-    }
-    if (typeof value === 'number' && Number.isFinite(value)) {
-      query[key] = value
-      continue
-    }
-    if (typeof value === 'boolean') {
-      query[key] = value
-    }
-  }
-  return query
-}
-
-const buildDefaultWriteBody = (options: Record<string, unknown>): Record<string, unknown> => {
-  const reserved = new Set([
-    'headers',
-    'query',
-    'method',
-    'requestBody',
-    'requestJson',
-    'requestData',
-    'requestPayload',
-    'json',
-    'data',
-    'payload',
-  ])
-
-  const body: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(options)) {
-    if (reserved.has(key)) continue
-    if (value !== undefined) {
-      body[key] = value
-    }
-  }
-  return body
-}
-
-const resolveHttpTransport = (requested?: string): 'fetch' | 'curl' => {
-  const normalized = (requested ?? '').trim().toLowerCase()
-  if (normalized === 'fetch' || normalized === 'curl') {
-    return normalized
-  }
-
-  const isBun = Boolean(process.versions?.bun)
-  if (!isTestRuntime() && isBun && process.platform === 'win32') {
-    return 'curl'
-  }
-
-  return 'fetch'
-}
-
-const readStream = async (stream: NodeJS.ReadableStream | null): Promise<Buffer> => {
-  if (!stream) return Buffer.from([])
-
-  return await new Promise<Buffer>((resolve) => {
-    const chunks: Buffer[] = []
-    let settled = false
-
-    const cleanup = () => {
-      stream.removeListener('data', onData)
-      stream.removeListener('end', onDone)
-      stream.removeListener('close', onDone)
-      stream.removeListener('error', onDone)
-    }
-
-    const settle = () => {
-      if (settled) return
-      settled = true
-      cleanup()
-      resolve(Buffer.concat(chunks))
-    }
-
-    const onDone = () => settle()
-
-    const onData = (chunk: unknown) => {
-      try {
-        if (typeof chunk === 'string') {
-          chunks.push(Buffer.from(chunk))
-          return
-        }
-
-        chunks.push(Buffer.from(chunk as ArrayBufferView))
-      } catch {
-        // best effort
-      }
-    }
-
-    stream.on('data', onData)
-    stream.on('end', onDone)
-    stream.on('close', onDone)
-    stream.on('error', onDone)
-  })
-}
-
-const callCurl = async (
-  requestUrl: string,
-  init: { method: string; headers: Record<string, string>; body?: string },
-  requestTimeoutMs: number,
-): Promise<{ status: number; ok: boolean; bodyText: string; responseHeaders: Record<string, string> }> => {
-  const curlExe = process.platform === 'win32' ? 'curl.exe' : 'curl'
-  const statusToken = crypto.randomBytes(8).toString('hex')
-  const marker = `\n__EXAMPLE_CURL_STATUS_${statusToken}__`
-  const writeOut = `${marker}%{http_code}${marker}`
-
-  const args: string[] = [
-    '--silent',
-    '--show-error',
-    '--location',
-    '--request', init.method,
-    '--write-out', writeOut,
-  ]
-
-  const timeoutSeconds = requestTimeoutMs > 0 ? Math.max(1, Math.ceil(requestTimeoutMs / 1000)) : null
-  if (timeoutSeconds !== null) {
-    args.push('--max-time', String(timeoutSeconds))
-    args.push('--connect-timeout', String(Math.max(1, Math.min(30, timeoutSeconds))))
-  }
-
-  for (const [name, value] of Object.entries(init.headers)) {
-    args.push('--header', `${name}: ${value}`)
-  }
-
-  if (init.body !== undefined) {
-    args.push('--data-binary', '@-')
-  }
-
-  args.push(requestUrl)
-
-  const child = spawn(curlExe, args, {
-    stdio: ['pipe', 'pipe', 'pipe'],
-    windowsHide: true,
-  })
-
-  const hardTimeoutMs = requestTimeoutMs > 0 ? requestTimeoutMs + 2_000 : null
-  let hardTimedOut = false
-  const hardTimeoutId = hardTimeoutMs
-    ? setTimeout(() => {
-        hardTimedOut = true
-        try {
-          child.kill()
-        } catch {
-          // best effort
-        }
-        try {
-          child.stdout?.destroy()
-        } catch {
-          // best effort
-        }
-        try {
-          child.stderr?.destroy()
-        } catch {
-          // best effort
-        }
-      }, hardTimeoutMs)
-    : null
-
-  if (init.body !== undefined) {
-    child.stdin.write(init.body)
-  }
-  child.stdin.end()
-
-  const stdoutPromise = readStream(child.stdout)
-  const stderrPromise = readStream(child.stderr)
-
-  let exitCode: number
-  try {
-    exitCode = await new Promise((resolve) => {
-      child.on('close', (code) => resolve(code ?? 0))
-      child.on('error', () => resolve(1))
-    })
-  } finally {
-    if (hardTimeoutId) {
-      clearTimeout(hardTimeoutId)
-    }
-  }
-
-  const [stdoutBytes, stderrBytes] = await Promise.all([stdoutPromise, stderrPromise])
-
-  if (hardTimedOut && requestTimeoutMs > 0) {
-    throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method} ${requestUrl}`)
-  }
-
-  const stdout = stdoutBytes.toString('utf8')
-  const stderr = stderrBytes.toString('utf8').trim()
-
-  if (exitCode !== 0) {
-    const message = stderr || `curl failed with exit code ${exitCode}`
-    if (exitCode === 28 && requestTimeoutMs > 0) {
-      throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method} ${requestUrl}`)
-    }
-    throw new Error(message)
-  }
-
-  const endMarkerIndex = stdout.lastIndexOf(marker)
-  const startMarkerIndex = endMarkerIndex > -1 ? stdout.lastIndexOf(marker, endMarkerIndex - 1) : -1
-  if (startMarkerIndex < 0 || endMarkerIndex < 0) {
-    throw new Error('Failed to parse curl response status code.')
-  }
-
-  const statusText = stdout.slice(startMarkerIndex + marker.length, endMarkerIndex).trim()
-  const status = Number(statusText)
-  const bodyText = stdout.slice(0, startMarkerIndex)
-
-  if (!Number.isFinite(status) || status <= 0) {
-    throw new Error(`Invalid curl status code: ${statusText}`)
-  }
-
-  return {
-    status,
-    ok: status >= 200 && status < 300,
-    bodyText,
-    responseHeaders: {},
-  }
-}
-
-const createMethod = (
-  feature: GitServiceFeature,
-  adapter: ReturnType<typeof createGitPlatformAdapter>,
-  defaults: { defaultOwner?: string; defaultRepo?: string },
-  requestTimeoutMs: number,
-  httpTransport: 'fetch' | 'curl',
-  log?: (message: string) => void,
-): GitServiceApiMethod => {
-  return async (...rawArgs: unknown[]) => {
-    const { args, options } = splitArgsAndOptions(rawArgs)
-    const { query: additionalQuery, method: methodOverride, ...bodyOptions } = (options as ApiCallOptions)
-
-    const baseMapping = await adapter.mapFeature({
-      feature,
-      args,
-      flagValues: {},
-      method: methodOverride,
-    })
-    const normalizedMethod = baseMapping.method.toUpperCase()
-
-    const { mapping, extraQuery } = normalizedMethod === 'GET'
-      ? (() => {
-          const { flags, unhandled } = mapFlagValues(feature, options)
-          return {
-            mapping: adapter.mapFeature({ feature, args, flagValues: flags, method: methodOverride }),
-            extraQuery: toQueryRecord(unhandled),
-          }
-        })()
-      : { mapping: Promise.resolve(baseMapping), extraQuery: {} }
-
-    const resolvedMapping = await mapping
-    const mergedQuery = {
-      ...(additionalQuery ?? {}),
-      ...(normalizedMethod === 'GET' ? extraQuery : {}),
-    }
-
-    const hydratedPath = resolvedMapping.mappedPath.map((segment) => {
-      if (segment === '{owner}' && defaults.defaultOwner) {
-        return defaults.defaultOwner
-      }
-
-      if (segment === '{repo}' && defaults.defaultRepo) {
-        return defaults.defaultRepo
-      }
-
-      return segment
-    })
-    assertResolvedMappedPath(hydratedPath, feature.path)
-
-    const requestBody = buildRequestBody(
-      resolvedMapping.method,
-      bodyOptions,
-      normalizedMethod === 'GET' ? {} : buildDefaultWriteBody(options),
-    )
-    const headers = {
-      ...toHeaderRecord(resolvedMapping.headers),
-      ...(options.headers ?? {}),
-    }
-
-    if (requestBody !== undefined && !headers['Content-Type']) {
-      headers['Content-Type'] = 'application/json'
-    }
-
-    const requestUrl = buildUrl(resolvedMapping.apiBase, hydratedPath, resolvedMapping.query, mergedQuery)
-    const requestInit: RequestInit = {
-      method: resolvedMapping.method,
-      headers,
-      body: requestBody !== undefined ? JSON.stringify(requestBody) : undefined,
-    }
-
-    const startedAt = Date.now()
-    log?.(`http:request ${resolvedMapping.method} ${requestUrl}`)
-    try {
-      const responseHeaders: Record<string, string> = {}
-      let status = 0
-      let ok = false
-      let parsedBody: unknown = ''
-
-      if (httpTransport === 'curl') {
-        const curlResult = await callCurl(
-          requestUrl,
-          {
-            method: resolvedMapping.method,
-            headers,
-            ...(requestInit.body !== undefined ? { body: String(requestInit.body) } : {}),
-          },
-          requestTimeoutMs,
-        )
-        status = curlResult.status
-        ok = curlResult.ok
-        const responseText = curlResult.bodyText
-        parsedBody = responseText
-        try {
-          parsedBody = JSON.parse(responseText)
-        } catch {
-          parsedBody = responseText
-        }
-      } else {
-        const timeoutSignal =
-          requestTimeoutMs > 0 && canUseAbortSignalTimeout()
-            ? (AbortSignal as unknown as { timeout: (ms: number) => AbortSignal }).timeout(requestTimeoutMs)
-            : null
-        const controller = !timeoutSignal && requestTimeoutMs > 0 ? new AbortController() : null
-        const timeoutId = controller ? setTimeout(() => controller.abort(), requestTimeoutMs) : null
-
-        try {
-          const response = await fetch(requestUrl, {
-            ...requestInit,
-            ...(timeoutSignal ? { signal: timeoutSignal } : {}),
-            ...(controller ? { signal: controller.signal } : {}),
-          })
-          status = response.status
-          ok = response.ok
-
-          const responseText = await response.text()
-          parsedBody = responseText
-          try {
-            parsedBody = JSON.parse(responseText)
-          } catch {
-            parsedBody = responseText
-          }
-
-          try {
-            response.headers.forEach((value, key) => {
-              responseHeaders[key.toLowerCase()] = value
-            })
-          } catch {
-            // best effort
-          }
-        } catch (error) {
-          if ((timeoutSignal && timeoutSignal.aborted) || controller?.signal.aborted) {
-            throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${resolvedMapping.method} ${requestUrl}`)
-          }
-          throw error
-        } finally {
-          if (timeoutId) {
-            clearTimeout(timeoutId)
-          }
-        }
-      }
-
-      log?.(`http:response ${resolvedMapping.method} ${requestUrl} -> ${status} (${Date.now() - startedAt}ms)`)
-      return {
-        mapping: {
-          ...resolvedMapping,
-          mappedPath: hydratedPath,
-        },
-        request: {
-          url: requestUrl,
-          method: resolvedMapping.method,
-          headers,
-          query: [...resolvedMapping.query],
-          body: requestBody,
-        },
-        response: {
-          headers: responseHeaders,
-        },
-        status,
-        ok,
-        body: parsedBody,
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      log?.(`http:error ${mapping.method} ${requestUrl} (${message})`)
-      throw error
-    }
-  }
-}
-
-const addFeatureToNamespace = (
-  root: GitServiceApi,
-  mountedPath: string[],
-  mappedFeature: GitServiceFeature,
-  adapter: ReturnType<typeof createGitPlatformAdapter>,
-  defaults: { defaultOwner?: string; defaultRepo?: string },
-  requestTimeoutMs: number,
-  httpTransport: 'fetch' | 'curl',
-  log?: (message: string) => void,
-) => {
-  let cursor: GitServiceApi = root
-  for (let i = 0; i < mountedPath.length; i += 1) {
-    const segment = mountedPath[i]
-    const isLeaf = i === mountedPath.length - 1
-
-    if (isLeaf) {
-      cursor[segment] = createMethod(mappedFeature, adapter, defaults, requestTimeoutMs, httpTransport, log)
-      continue
-    }
-
-    if (!cursor[segment]) {
-      cursor[segment] = {}
-    }
-
-    const node = cursor[segment]
-    if (typeof node !== 'object' || node === null) {
-      cursor[segment] = {}
-    }
-
-    cursor = cursor[segment] as GitServiceApi
-  }
-}
-
-export const createGitServiceApi = (options: GitServiceApiFactoryOptions = {}): GitServiceApi => {
-  const config = getGitPlatformConfig(options.config)
-  const adapter = createGitPlatformAdapter({
-    config,
-    ...(options.swaggerSpec ? { swaggerSpec: options.swaggerSpec } : {}),
-  })
-  const requestTimeoutMs = parseRequestTimeoutMs(options.requestTimeoutMs) ?? resolveDefaultRequestTimeoutMs()
-  const httpTransport = resolveHttpTransport(options.httpTransport ?? process.env.EXAMPLE_GIT_HTTP_TRANSPORT)
-  const log = options.log
-
-  const defaults = {
-    defaultOwner: options.defaultOwner,
-    defaultRepo: options.defaultRepo,
-  }
-
-  const root: GitServiceApi = {}
-
-  for (const feature of gitServiceFeatureSpec.features) {
-    if (feature.path.length === 0) {
-      continue
-    }
-
-    addFeatureToNamespace(root, feature.path, feature, adapter, defaults, requestTimeoutMs, httpTransport, log)
-
-    if (feature.path[0] !== 'repo') {
-      addFeatureToNamespace(
-        root,
-        ['repo', ...feature.path],
-        feature,
-        adapter,
-        defaults,
-        requestTimeoutMs,
-        httpTransport,
-        log,
-      )
-    }
-  }
-
-  attachGitLabelManagementApi(root, defaults)
-  attachGitActionsApi(root, {
-    config,
-    defaults,
-    requestTimeoutMs,
-    log,
-  })
-  attachGitCiApi(root, {
-    config,
-    defaults,
-    requestTimeoutMs,
-    log,
-  })
-
-  return root
-}
-
-const createUnavailableGitServiceApi = (error: Error): GitServiceApi => {
-  return new Proxy(
-    {},
-    {
-      get: (): never => {
-        throw error
-      },
-    },
-  ) as GitServiceApi
-}
-
-export const gitServiceApi: GitServiceApi = (() => {
-  try {
-    return createGitServiceApi()
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    return createUnavailableGitServiceApi(
-      new Error(`Failed to initialize gitServiceApi singleton: ${message}`),
-    )
-  }
-})()
+import { createGitPlatformAdapter, type GitPlatformAdapterFactoryDeps } from './platform'
+import { getGitPlatformConfig, type GitPlatformConfig } from './platform/config'
+import { type GitServiceFlag, type GitServiceFeature, gitServiceFeatureSpec } from './git-service-feature-spec.generated'
+import { type GitApiFeatureMapping } from './platform/gitea-adapter'
+import { attachGitLabelManagementApi } from './label-management'
+import { attachGitActionsApi } from './actions-api'
+import { attachGitCiApi } from './ci-api'
+import { spawn } from 'node:child_process'
+import crypto from 'node:crypto'
+
+export interface GitServiceApiFactoryOptions {
+  config?: Partial<GitPlatformConfig>
+  defaultOwner?: string
+  defaultRepo?: string
+  swaggerSpec?: GitPlatformAdapterFactoryDeps['swaggerSpec']
+  requestTimeoutMs?: number
+  httpTransport?: 'fetch' | 'curl'
+  log?: (message: string) => void
+}
+
+export interface GitServiceApiExecutionResult<T = unknown> {
+  mapping: GitApiFeatureMapping
+  request: {
+    url: string
+    method: string
+    headers: Record<string, string>
+    query: string[]
+    body?: unknown
+  }
+  response: {
+    headers: Record<string, string>
+  }
+  status: number
+  ok: boolean
+  body: T
+}
+
+export type GitServiceApiMethod = (...args: unknown[]) => Promise<GitServiceApiExecutionResult>
+
+export type GitServiceApi = {
+  [key: string]: GitServiceApi | GitServiceApiMethod
+}
+
+type ApiCallOptions = {
+  method?: string
+  requestBody?: unknown
+  requestJson?: unknown
+  requestData?: unknown
+  requestPayload?: unknown
+  json?: unknown
+  data?: unknown
+  payload?: unknown
+  headers?: Record<string, string>
+  query?: Record<string, string | number | boolean>
+}
+
+interface NormalizedCall {
+  args: string[]
+  options: Record<string, unknown>
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const parseRequestTimeoutMs = (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 resolveDefaultRequestTimeoutMs = (): number => {
+  const fromEnv =
+    parseRequestTimeoutMs(process.env.EXAMPLE_GIT_REQUEST_TIMEOUT_MS) ??
+    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_REQUEST_TIMEOUT_MS) ??
+    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_TIMEOUT_MS)
+
+  return fromEnv ?? DEFAULT_REQUEST_TIMEOUT_MS
+}
+
+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 splitArgsAndOptions = (rawArgs: unknown[]): NormalizedCall => {
+  if (rawArgs.length === 0 || !isPlainObject(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 normalizeFlagLookup = (name: string): string =>
+  name.replace(/^--/, '').trim().toLowerCase()
+
+const mapFlagValues = (
+  feature: GitServiceFeature,
+  options: Record<string, unknown>,
+): {
+  flags: Record<string, string | boolean>
+  unhandled: Record<string, unknown>
+} => {
+  const flags: Record<string, string | boolean> = {}
+  const unhandled: Record<string, unknown> = {}
+  const alias = new Map<string, string>()
+
+  for (const flag of feature.flags) {
+    const canonical = normalizeFlagLookup(flag.name)
+    alias.set(canonical, flag.name)
+  }
+
+  const reserved = new Set([
+    'json',
+    'data',
+    'payload',
+    'headers',
+    'query',
+    'method',
+    // Common path params / context keys (do not leak into query params for GET tools).
+    'owner',
+    'repo',
+    'index',
+    'number',
+    'prnumber',
+    'issuenumber',
+    'mergemethod',
+    'requestbody',
+    'requestjson',
+    'requestdata',
+    'requestpayload',
+  ])
+
+  for (const [key, value] of Object.entries(options)) {
+    const normalizedKey = normalizeFlagLookup(key)
+
+    if (value === undefined) {
+      continue
+    }
+
+    if (reserved.has(normalizedKey)) {
+      continue
+    }
+
+    if (alias.has(normalizedKey)) {
+      const canonical = alias.get(normalizedKey)
+      if (canonical) {
+        flags[canonical] = typeof value === 'boolean' ? value : String(value)
+      }
+      continue
+    }
+
+    unhandled[key] = value
+  }
+
+  return { flags, unhandled }
+}
+
+const buildRequestBody = (
+  method: string,
+  options: Record<string, unknown>,
+  defaultBody: Record<string, unknown>,
+): unknown | undefined => {
+  const normalizedMethod = method.toUpperCase()
+  const explicit =
+    options.requestBody ??
+    options.requestJson ??
+    options.requestData ??
+    options.requestPayload ??
+    options.json ??
+    options.data ??
+    options.payload
+
+  if (explicit !== undefined) {
+    return explicit
+  }
+
+  if (!['POST', 'PUT', 'PATCH'].includes(normalizedMethod)) {
+    return undefined
+  }
+
+  if (Object.keys(defaultBody).length > 0) {
+    return defaultBody
+  }
+
+  return undefined
+}
+
+const buildUrl = (
+  apiBase: string,
+  mappedPath: string[],
+  query: string[],
+  additionalQuery: Record<string, string | number | boolean> = {},
+): string => {
+  const path = `${apiBase}/${mappedPath.join('/')}`
+  const url = new URL(path)
+
+  for (const queryPair of query) {
+    const [name, value = ''] = queryPair.split('=', 2)
+    if (!name) {
+      continue
+    }
+
+    url.searchParams.set(name, value)
+  }
+
+  for (const [name, value] of Object.entries(additionalQuery)) {
+    url.searchParams.set(name, String(value))
+  }
+
+  return url.toString()
+}
+
+const unresolvedPathParamPattern = /^\{[^{}]+\}$/
+
+const extractPathParamValue = (value: unknown): string | null => {
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    return trimmed ? trimmed : null
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(Math.trunc(value))
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 'true' : 'false'
+  }
+
+  return null
+}
+
+const hydrateMappedPath = (
+  mappedPath: string[],
+  defaults: { defaultOwner?: string; defaultRepo?: string },
+  options: Record<string, unknown>,
+): string[] => {
+  const owner = extractPathParamValue(options.owner) ?? defaults.defaultOwner ?? null
+  const repo = extractPathParamValue(options.repo) ?? defaults.defaultRepo ?? null
+
+  return mappedPath.map((segment) => {
+    if (segment === '{owner}' && owner) return owner
+    if (segment === '{repo}' && repo) return repo
+
+    if (!unresolvedPathParamPattern.test(segment)) {
+      return segment
+    }
+
+    const key = segment.slice(1, -1).trim()
+    if (!key) return segment
+
+    // Common aliases used by humans/LLMs.
+    const candidates: unknown[] =
+      key === 'index'
+        ? [options.index, options.number, (options as Record<string, unknown>).prNumber, (options as Record<string, unknown>).issueNumber]
+        : [options[key]]
+
+    const hydrated = candidates.map(extractPathParamValue).find((value): value is string => Boolean(value)) ?? null
+    return hydrated ?? segment
+  })
+}
+
+const assertResolvedMappedPath = (
+  mappedPath: string[],
+  featurePath: string[],
+): void => {
+  const unresolved = mappedPath.filter((segment) => unresolvedPathParamPattern.test(segment))
+  if (unresolved.length === 0) {
+    return
+  }
+
+  throw new Error(
+    `Missing required path arguments for "${featurePath.join('.')}". Unresolved parameters: ${unresolved.join(', ')}`,
+  )
+}
+
+const canUseAbortSignalTimeout = (): boolean =>
+  typeof AbortSignal !== 'undefined' && typeof (AbortSignal as unknown as { timeout?: unknown }).timeout === 'function'
+
+const isTestRuntime = (): boolean =>
+  Boolean(process.env.VITEST) || process.env.NODE_ENV === 'test'
+
+const toQueryRecord = (raw: Record<string, unknown>): Record<string, string | number | boolean> => {
+  const query: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === 'string') {
+      query[key] = value
+      continue
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      query[key] = value
+      continue
+    }
+    if (typeof value === 'boolean') {
+      query[key] = value
+    }
+  }
+  return query
+}
+
+const buildDefaultWriteBody = (options: Record<string, unknown>): Record<string, unknown> => {
+  const reserved = new Set([
+    'owner',
+    'repo',
+    'index',
+    'number',
+    'prNumber',
+    'issueNumber',
+    'mergeMethod',
+    'headers',
+    'query',
+    'method',
+    'requestBody',
+    'requestJson',
+    'requestData',
+    'requestPayload',
+    'json',
+    'data',
+    'payload',
+  ])
+
+  const body: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(options)) {
+    if (reserved.has(key)) continue
+    if (value !== undefined) {
+      body[key] = value
+    }
+  }
+  return body
+}
+
+const resolveHttpTransport = (requested?: string): 'fetch' | 'curl' => {
+  const normalized = (requested ?? '').trim().toLowerCase()
+  if (normalized === 'fetch' || normalized === 'curl') {
+    return normalized
+  }
+
+  const isBun = Boolean(process.versions?.bun)
+  if (!isTestRuntime() && isBun && process.platform === 'win32') {
+    return 'curl'
+  }
+
+  return 'fetch'
+}
+
+const readStream = async (stream: NodeJS.ReadableStream | null): Promise<Buffer> => {
+  if (!stream) return Buffer.from([])
+
+  return await new Promise<Buffer>((resolve) => {
+    const chunks: Buffer[] = []
+    let settled = false
+
+    const cleanup = () => {
+      stream.removeListener('data', onData)
+      stream.removeListener('end', onDone)
+      stream.removeListener('close', onDone)
+      stream.removeListener('error', onDone)
+    }
+
+    const settle = () => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolve(Buffer.concat(chunks))
+    }
+
+    const onDone = () => settle()
+
+    const onData = (chunk: unknown) => {
+      try {
+        if (typeof chunk === 'string') {
+          chunks.push(Buffer.from(chunk))
+          return
+        }
+
+        chunks.push(Buffer.from(chunk as ArrayBufferView))
+      } catch {
+        // best effort
+      }
+    }
+
+    stream.on('data', onData)
+    stream.on('end', onDone)
+    stream.on('close', onDone)
+    stream.on('error', onDone)
+  })
+}
+
+const callCurl = async (
+  requestUrl: string,
+  init: { method: string; headers: Record<string, string>; body?: string },
+  requestTimeoutMs: number,
+): Promise<{ status: number; ok: boolean; bodyText: string; responseHeaders: Record<string, string> }> => {
+  const curlExe = process.platform === 'win32' ? 'curl.exe' : 'curl'
+  const statusToken = crypto.randomBytes(8).toString('hex')
+  const marker = `\n__EXAMPLE_CURL_STATUS_${statusToken}__`
+  const writeOut = `${marker}%{http_code}${marker}`
+
+  const args: string[] = [
+    '--silent',
+    '--show-error',
+    '--location',
+    '--request', init.method,
+    '--write-out', writeOut,
+  ]
+
+  const timeoutSeconds = requestTimeoutMs > 0 ? Math.max(1, Math.ceil(requestTimeoutMs / 1000)) : null
+  if (timeoutSeconds !== null) {
+    args.push('--max-time', String(timeoutSeconds))
+    args.push('--connect-timeout', String(Math.max(1, Math.min(30, timeoutSeconds))))
+  }
+
+  for (const [name, value] of Object.entries(init.headers)) {
+    args.push('--header', `${name}: ${value}`)
+  }
+
+  if (init.body !== undefined) {
+    args.push('--data-binary', '@-')
+  }
+
+  args.push(requestUrl)
+
+  const child = spawn(curlExe, args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  })
+
+  const hardTimeoutMs = requestTimeoutMs > 0 ? requestTimeoutMs + 2_000 : null
+  let hardTimedOut = false
+  const hardTimeoutId = hardTimeoutMs
+    ? setTimeout(() => {
+        hardTimedOut = true
+        try {
+          child.kill()
+        } catch {
+          // best effort
+        }
+        try {
+          child.stdout?.destroy()
+        } catch {
+          // best effort
+        }
+        try {
+          child.stderr?.destroy()
+        } catch {
+          // best effort
+        }
+      }, hardTimeoutMs)
+    : null
+
+  if (init.body !== undefined) {
+    child.stdin.write(init.body)
+  }
+  child.stdin.end()
+
+  const stdoutPromise = readStream(child.stdout)
+  const stderrPromise = readStream(child.stderr)
+
+  let exitCode: number
+  try {
+    exitCode = await new Promise((resolve) => {
+      child.on('close', (code) => resolve(code ?? 0))
+      child.on('error', () => resolve(1))
+    })
+  } finally {
+    if (hardTimeoutId) {
+      clearTimeout(hardTimeoutId)
+    }
+  }
+
+  const [stdoutBytes, stderrBytes] = await Promise.all([stdoutPromise, stderrPromise])
+
+  if (hardTimedOut && requestTimeoutMs > 0) {
+    throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method} ${requestUrl}`)
+  }
+
+  const stdout = stdoutBytes.toString('utf8')
+  const stderr = stderrBytes.toString('utf8').trim()
+
+  if (exitCode !== 0) {
+    const message = stderr || `curl failed with exit code ${exitCode}`
+    if (exitCode === 28 && requestTimeoutMs > 0) {
+      throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method} ${requestUrl}`)
+    }
+    throw new Error(message)
+  }
+
+  const endMarkerIndex = stdout.lastIndexOf(marker)
+  const startMarkerIndex = endMarkerIndex > -1 ? stdout.lastIndexOf(marker, endMarkerIndex - 1) : -1
+  if (startMarkerIndex < 0 || endMarkerIndex < 0) {
+    throw new Error('Failed to parse curl response status code.')
+  }
+
+  const statusText = stdout.slice(startMarkerIndex + marker.length, endMarkerIndex).trim()
+  const status = Number(statusText)
+  const bodyText = stdout.slice(0, startMarkerIndex)
+
+  if (!Number.isFinite(status) || status <= 0) {
+    throw new Error(`Invalid curl status code: ${statusText}`)
+  }
+
+  return {
+    status,
+    ok: status >= 200 && status < 300,
+    bodyText,
+    responseHeaders: {},
+  }
+}
+
+const createMethod = (
+  feature: GitServiceFeature,
+  adapter: ReturnType<typeof createGitPlatformAdapter>,
+  defaults: { defaultOwner?: string; defaultRepo?: string },
+  requestTimeoutMs: number,
+  httpTransport: 'fetch' | 'curl',
+  log?: (message: string) => void,
+): GitServiceApiMethod => {
+  return async (...rawArgs: unknown[]) => {
+    const { args, options } = splitArgsAndOptions(rawArgs)
+    const { query: additionalQuery, method: methodOverride, ...bodyOptions } = (options as ApiCallOptions)
+
+    const baseMapping = await adapter.mapFeature({
+      feature,
+      args,
+      flagValues: {},
+      method: methodOverride,
+    })
+    const normalizedMethod = baseMapping.method.toUpperCase()
+
+    const { mapping, extraQuery } = normalizedMethod === 'GET'
+      ? (() => {
+          const { flags, unhandled } = mapFlagValues(feature, options)
+          return {
+            mapping: adapter.mapFeature({ feature, args, flagValues: flags, method: methodOverride }),
+            extraQuery: toQueryRecord(unhandled),
+          }
+        })()
+      : { mapping: Promise.resolve(baseMapping), extraQuery: {} }
+
+    const resolvedMapping = await mapping
+    const mergedQuery = {
+      ...(additionalQuery ?? {}),
+      ...(normalizedMethod === 'GET' ? extraQuery : {}),
+    }
+
+    const hydratedPath = hydrateMappedPath(resolvedMapping.mappedPath, defaults, options)
+    assertResolvedMappedPath(hydratedPath, feature.path)
+
+    const defaultWriteBody = normalizedMethod === 'GET' ? {} : buildDefaultWriteBody(options)
+    let requestBody = buildRequestBody(
+      resolvedMapping.method,
+      bodyOptions,
+      defaultWriteBody,
+    )
+
+    // LLM-friendly default: merging a PR should not require the caller to know Gitea's
+    // merge payload shape. If no explicit body is provided, default to "merge".
+    if (
+      requestBody === undefined &&
+      normalizedMethod !== 'GET' &&
+      feature.path.length >= 2 &&
+      feature.path[feature.path.length - 2] === 'pr' &&
+      feature.path[feature.path.length - 1] === 'merge'
+    ) {
+      requestBody = {
+        Do: extractPathParamValue((options as Record<string, unknown>).mergeMethod) ?? 'merge',
+      }
+    }
+    const headers = {
+      ...toHeaderRecord(resolvedMapping.headers),
+      ...(options.headers ?? {}),
+    }
+
+    const isWriteMethod = ['POST', 'PUT', 'PATCH'].includes(normalizedMethod)
+    if (isWriteMethod && !headers['Content-Type']) {
+      headers['Content-Type'] = 'application/json'
+    }
+
+    const requestUrl = buildUrl(resolvedMapping.apiBase, hydratedPath, resolvedMapping.query, mergedQuery)
+    const requestInit: RequestInit = {
+      method: resolvedMapping.method,
+      headers,
+      body: requestBody !== undefined ? JSON.stringify(requestBody) : undefined,
+    }
+
+    const startedAt = Date.now()
+    log?.(`http:request ${resolvedMapping.method} ${requestUrl}`)
+    try {
+      const responseHeaders: Record<string, string> = {}
+      let status = 0
+      let ok = false
+      let parsedBody: unknown = ''
+
+      if (httpTransport === 'curl') {
+        const curlResult = await callCurl(
+          requestUrl,
+          {
+            method: resolvedMapping.method,
+            headers,
+            ...(requestInit.body !== undefined ? { body: String(requestInit.body) } : {}),
+          },
+          requestTimeoutMs,
+        )
+        status = curlResult.status
+        ok = curlResult.ok
+        const responseText = curlResult.bodyText
+        parsedBody = responseText
+        try {
+          parsedBody = JSON.parse(responseText)
+        } catch {
+          parsedBody = responseText
+        }
+      } else {
+        const timeoutSignal =
+          requestTimeoutMs > 0 && canUseAbortSignalTimeout()
+            ? (AbortSignal as unknown as { timeout: (ms: number) => AbortSignal }).timeout(requestTimeoutMs)
+            : null
+        const controller = !timeoutSignal && requestTimeoutMs > 0 ? new AbortController() : null
+        const timeoutId = controller ? setTimeout(() => controller.abort(), requestTimeoutMs) : null
+
+        try {
+          const response = await fetch(requestUrl, {
+            ...requestInit,
+            ...(timeoutSignal ? { signal: timeoutSignal } : {}),
+            ...(controller ? { signal: controller.signal } : {}),
+          })
+          status = response.status
+          ok = response.ok
+
+          const responseText = await response.text()
+          parsedBody = responseText
+          try {
+            parsedBody = JSON.parse(responseText)
+          } catch {
+            parsedBody = responseText
+          }
+
+          try {
+            response.headers.forEach((value, key) => {
+              responseHeaders[key.toLowerCase()] = value
+            })
+          } catch {
+            // best effort
+          }
+        } catch (error) {
+          if ((timeoutSignal && timeoutSignal.aborted) || controller?.signal.aborted) {
+            throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${resolvedMapping.method} ${requestUrl}`)
+          }
+          throw error
+        } finally {
+          if (timeoutId) {
+            clearTimeout(timeoutId)
+          }
+        }
+      }
+
+      log?.(`http:response ${resolvedMapping.method} ${requestUrl} -> ${status} (${Date.now() - startedAt}ms)`)
+      return {
+        mapping: {
+          ...resolvedMapping,
+          mappedPath: hydratedPath,
+        },
+        request: {
+          url: requestUrl,
+          method: resolvedMapping.method,
+          headers,
+          query: [...resolvedMapping.query],
+          body: requestBody,
+        },
+        response: {
+          headers: responseHeaders,
+        },
+        status,
+        ok,
+        body: parsedBody,
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      log?.(`http:error ${mapping.method} ${requestUrl} (${message})`)
+      throw error
+    }
+  }
+}
+
+const addFeatureToNamespace = (
+  root: GitServiceApi,
+  mountedPath: string[],
+  mappedFeature: GitServiceFeature,
+  adapter: ReturnType<typeof createGitPlatformAdapter>,
+  defaults: { defaultOwner?: string; defaultRepo?: string },
+  requestTimeoutMs: number,
+  httpTransport: 'fetch' | 'curl',
+  log?: (message: string) => void,
+) => {
+  let cursor: GitServiceApi = root
+  for (let i = 0; i < mountedPath.length; i += 1) {
+    const segment = mountedPath[i]
+    const isLeaf = i === mountedPath.length - 1
+
+    if (isLeaf) {
+      cursor[segment] = createMethod(mappedFeature, adapter, defaults, requestTimeoutMs, httpTransport, log)
+      continue
+    }
+
+    if (!cursor[segment]) {
+      cursor[segment] = {}
+    }
+
+    const node = cursor[segment]
+    if (typeof node !== 'object' || node === null) {
+      cursor[segment] = {}
+    }
+
+    cursor = cursor[segment] as GitServiceApi
+  }
+}
+
+export const createGitServiceApi = (options: GitServiceApiFactoryOptions = {}): GitServiceApi => {
+  const config = getGitPlatformConfig(options.config)
+  const adapter = createGitPlatformAdapter({
+    config,
+    ...(options.swaggerSpec ? { swaggerSpec: options.swaggerSpec } : {}),
+  })
+  const requestTimeoutMs = parseRequestTimeoutMs(options.requestTimeoutMs) ?? resolveDefaultRequestTimeoutMs()
+  const httpTransport = resolveHttpTransport(options.httpTransport ?? process.env.EXAMPLE_GIT_HTTP_TRANSPORT)
+  const log = options.log
+
+  const defaults = {
+    defaultOwner: options.defaultOwner,
+    defaultRepo: options.defaultRepo,
+  }
+
+  const root: GitServiceApi = {}
+
+  for (const feature of gitServiceFeatureSpec.features) {
+    if (feature.path.length === 0) {
+      continue
+    }
+
+    addFeatureToNamespace(root, feature.path, feature, adapter, defaults, requestTimeoutMs, httpTransport, log)
+
+    if (feature.path[0] !== 'repo') {
+      addFeatureToNamespace(
+        root,
+        ['repo', ...feature.path],
+        feature,
+        adapter,
+        defaults,
+        requestTimeoutMs,
+        httpTransport,
+        log,
+      )
+    }
+  }
+
+  attachGitLabelManagementApi(root, defaults)
+  attachGitActionsApi(root, {
+    config,
+    defaults,
+    requestTimeoutMs,
+    log,
+  })
+  attachGitCiApi(root, {
+    config,
+    defaults,
+    requestTimeoutMs,
+    log,
+  })
+
+  return root
+}
+
+const createUnavailableGitServiceApi = (error: Error): GitServiceApi => {
+  return new Proxy(
+    {},
+    {
+      get: (): never => {
+        throw error
+      },
+    },
+  ) as GitServiceApi
+}
+
+export const gitServiceApi: GitServiceApi = (() => {
+  try {
+    return createGitServiceApi()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return createUnavailableGitServiceApi(
+      new Error(`Failed to initialize gitServiceApi singleton: ${message}`),
+    )
+  }
+})()