@foundation0/git 1.2.3 → 1.2.4

package/README.md

@@ -80,12 +80,18 @@ type GitServiceApiExecutionResult = {
 
 ## Core request shapes
 
-Use `data`, `json`, `body`, or `payload` for request bodies on write methods.
+Write methods accept request fields directly (recommended), or you can set the raw request body with `data` / `json` / `payload` / `requestBody`.
 
 ```ts
 await api.repo.issue.create({
-  data: { title: 'Bug report', body: 'Describe issue details' },
-  query: { labels: 'bug', assignee: 'bot' },
+  title: 'Bug report',
+  body: 'Describe issue details',
+  labels: ['bug'],
+})
+
+// equivalent explicit-body form
+await api.repo.issue.create({
+  data: { title: 'Bug report', body: 'Describe issue details', labels: ['bug'] },
 })
 ```
 

package/mcp/README.md

@@ -209,3 +209,8 @@ Tips:
 - `normalizeToolCallNameForServer(prefix, toolName)`
 - Includes label-management tools exposed from the API object:
   `repo.label.listManaged`, `repo.label.getByName`, `repo.label.upsert`, and `repo.label.deleteByName`
+- Includes Gitea Actions convenience tools exposed from the API object (best-effort helpers):
+  `repo.actions.tasks.list`, `repo.actions.jobs.logs`, `repo.actions.jobs.logsTail`, `repo.actions.jobs.logsForRunTail`,
+  and `repo.actions.artifacts.downloadZipUrl`
+- Includes a discovery helper:
+  `help.actionsLogs` (also available under `repo.help.actionsLogs`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundation0/git",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Foundation 0 Git API and MCP server",
   "type": "module",
   "bin": {

package/src/actions-api.ts

@@ -0,0 +1,616 @@
+import type { GitServiceApi, GitServiceApiExecutionResult, GitServiceApiMethod } from './git-service-api'
+import type { GitApiFeatureMapping } from './platform/gitea-adapter'
+import type { GitPlatformConfig } from './platform/config'
+
+const DEFAULT_LOG_TAIL_LINES = 200
+const DEFAULT_HTTP_TIMEOUT_MS = 60_000
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const toTrimmedString = (value: unknown): string | null => {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+const toPositiveInteger = (value: unknown): number | null => {
+  const candidate = Number(value)
+  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
+    return null
+  }
+  return candidate
+}
+
+const buildApiBase = (host: string): string => {
+  const sanitized = host.replace(/\/$/, '')
+  if (sanitized.endsWith('/api/v1')) {
+    return sanitized
+  }
+  return `${sanitized}/api/v1`
+}
+
+const toQueryArray = (query: Record<string, string | number | boolean>): string[] =>
+  Object.entries(query).map(([key, value]) => `${key}=${String(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)),
+  )
+
+type RawCall = {
+  args: string[]
+  options: Record<string, unknown>
+}
+
+const splitArgsAndOptions = (rawArgs: unknown[]): RawCall => {
+  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 },
+  }
+}
+
+type Scope = {
+  owner?: string
+  repo?: string
+  options: Record<string, unknown>
+}
+
+export interface GitActionsApiDefaults {
+  defaultOwner?: string
+  defaultRepo?: string
+}
+
+export interface GitActionsApiContext {
+  config: Pick<GitPlatformConfig, 'giteaHost' | 'giteaToken' | 'platform'>
+  defaults?: GitActionsApiDefaults
+  requestTimeoutMs?: number
+  log?: (message: string) => void
+}
+
+const normalizeScopeArgs = (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown): Scope => {
+  const options: Record<string, unknown> = {}
+  let owner: string | undefined
+  let repo: string | undefined
+
+  const absorb = (value: unknown): string | undefined => {
+    if (value === undefined || value === null) {
+      return undefined
+    }
+
+    if (isRecord(value)) {
+      Object.assign(options, value)
+      return undefined
+    }
+
+    const asText = String(value).trim()
+    return asText.length > 0 ? asText : undefined
+  }
+
+  owner = absorb(ownerOrOptions)
+  repo = absorb(repoOrOptions)
+
+  if (isRecord(maybeOptions)) {
+    Object.assign(options, maybeOptions)
+  }
+
+  return {
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+    options,
+  }
+}
+
+const resolveOwnerRepo = (
+  scope: Pick<Scope, 'owner' | 'repo'>,
+  defaults: GitActionsApiDefaults,
+): { 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 }
+}
+
+const resolveOwnerRepoFromArgs = (
+  args: string[],
+  scope: Pick<Scope, 'owner' | 'repo'>,
+  defaults: GitActionsApiDefaults,
+): { owner: string; repo: string; rest: string[] } => {
+  if (scope.owner || scope.repo) {
+    const resolved = resolveOwnerRepo(scope, defaults)
+    return { ...resolved, rest: args }
+  }
+
+  if (args.length >= 2) {
+    return { owner: args[0], repo: args[1], rest: args.slice(2) }
+  }
+
+  if (args.length === 1) {
+    const split = args[0].split('/')
+    if (split.length === 2 && split[0] && split[1]) {
+      return { owner: split[0], repo: split[1], rest: [] }
+    }
+  }
+
+  const resolved = resolveOwnerRepo({}, defaults)
+  return { ...resolved, rest: args }
+}
+
+const resolveOwnerRepoAndId = (
+  rawArgs: unknown[],
+  defaults: GitActionsApiDefaults,
+): { owner: string; repo: string; id: string; options: Record<string, unknown> } => {
+  const parsed = splitArgsAndOptions(rawArgs)
+  const args = parsed.args.map((value) => value.trim()).filter((value) => value.length > 0)
+
+  if (args.length === 0) {
+    throw new Error('ID is required.')
+  }
+
+  if (args.length === 1) {
+    const { owner, repo } = resolveOwnerRepo({}, defaults)
+    return { owner, repo, id: args[0], options: parsed.options }
+  }
+
+  if (args.length === 2) {
+    if (args[0].includes('/')) {
+      const split = args[0].split('/')
+      if (split.length === 2 && split[0] && split[1]) {
+        return { owner: split[0], repo: split[1], id: args[1], options: parsed.options }
+      }
+    }
+
+    throw new Error(
+      'Ambiguous arguments. Pass <id> (and rely on defaults), or pass <owner> <repo> <id>, or pass <owner/repo> <id>.',
+    )
+  }
+
+  return { owner: args[0], repo: args[1], id: args[2], options: parsed.options }
+}
+
+const resolveTimeoutMs = (value: unknown, fallback: number): number => {
+  const parsed = toPositiveInteger(value)
+  return parsed ?? fallback
+}
+
+const readTextBody = async (response: Response): Promise<string> => {
+  try {
+    return await response.text()
+  } catch {
+    return ''
+  }
+}
+
+const readBody = async (response: Response): Promise<unknown> => {
+  const contentType = response.headers.get('content-type') ?? ''
+  const text = await readTextBody(response)
+  if (contentType.toLowerCase().includes('application/json')) {
+    try {
+      return JSON.parse(text)
+    } catch {
+      return text
+    }
+  }
+  return text
+}
+
+const requestGitea = async (
+  ctx: GitActionsApiContext,
+  featurePath: string[],
+  owner: string,
+  repo: string,
+  method: string,
+  pathTail: string[],
+  options: Record<string, unknown> = {},
+  requestInitOverrides: Partial<RequestInit> = {},
+): Promise<GitServiceApiExecutionResult<unknown>> => {
+  if (ctx.config.platform !== 'GITEA') {
+    throw new Error(`Actions API only supports GITEA platform, got ${ctx.config.platform}`)
+  }
+
+  const apiBase = buildApiBase(ctx.config.giteaHost)
+  const mappedPath = ['repos', owner, repo, 'actions', ...pathTail]
+
+  const query = isRecord(options.query) ? (options.query as Record<string, unknown>) : {}
+  const queryRecord: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(query)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      queryRecord[key] = value
+    }
+  }
+
+  const url = new URL(`${apiBase}/${mappedPath.join('/')}`)
+  for (const [key, value] of Object.entries(queryRecord)) {
+    url.searchParams.set(key, String(value))
+  }
+
+  const headersList: string[] = []
+  headersList.push('Accept: */*')
+  if (ctx.config.giteaToken) {
+    headersList.push(`Authorization: token ${ctx.config.giteaToken}`)
+  }
+
+  const headers = toHeaderRecord(headersList)
+
+  const requestTimeoutMs = resolveTimeoutMs(options.requestTimeoutMs ?? ctx.requestTimeoutMs, DEFAULT_HTTP_TIMEOUT_MS)
+  const timeoutSignal =
+    requestTimeoutMs > 0 && typeof (AbortSignal as unknown as { timeout?: (ms: number) => AbortSignal }).timeout === 'function'
+      ? (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 {
+    ctx.log?.(`actions:http:request ${method.toUpperCase()} ${url.toString()}`)
+    const response = await fetch(url.toString(), {
+      method: method.toUpperCase(),
+      headers,
+      ...(timeoutSignal ? { signal: timeoutSignal } : {}),
+      ...(controller ? { signal: controller.signal } : {}),
+      ...requestInitOverrides,
+    })
+
+    const body = await readBody(response)
+    const responseHeaders: Record<string, string> = {}
+    try {
+      response.headers.forEach((value, key) => {
+        responseHeaders[key.toLowerCase()] = value
+      })
+    } catch {
+      // best effort
+    }
+
+    const mapping: GitApiFeatureMapping = {
+      platform: 'GITEA',
+      featurePath,
+      mappedPath,
+      method: method.toUpperCase(),
+      query: toQueryArray(queryRecord),
+      headers: headersList,
+      apiBase,
+      swaggerPath: `/${mappedPath.join('/')}`,
+      mapped: true,
+      reason: 'Direct Gitea Actions API call',
+    }
+
+    return {
+      mapping,
+      request: {
+        url: url.toString(),
+        method: method.toUpperCase(),
+        headers,
+        query: toQueryArray(queryRecord),
+      },
+      response: {
+        headers: responseHeaders,
+      },
+      status: response.status,
+      ok: response.ok,
+      body,
+    }
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+const tailText = (input: string, options: { contains?: string; maxLines?: number; maxBytes?: number }): string => {
+  const contains = toTrimmedString(options.contains ?? null) ?? null
+  const maxLines = toPositiveInteger(options.maxLines) ?? DEFAULT_LOG_TAIL_LINES
+  const maxBytes = toPositiveInteger(options.maxBytes)
+
+  let text = input
+
+  if (contains) {
+    text = text
+      .split(/\r?\n/g)
+      .filter((line) => line.includes(contains))
+      .join('\n')
+  }
+
+  if (maxLines > 0) {
+    const lines = text.split(/\r?\n/g)
+    text = lines.slice(Math.max(0, lines.length - maxLines)).join('\n')
+  }
+
+  if (maxBytes && maxBytes > 0) {
+    const buf = Buffer.from(text, 'utf8')
+    if (buf.length > maxBytes) {
+      text = buf.subarray(buf.length - maxBytes).toString('utf8')
+    }
+  }
+
+  return text
+}
+
+export type GitActionsHelpBody = {
+  summary: string
+  suggestedCalls: Array<{
+    tool: string
+    args: string[]
+    options?: Record<string, unknown>
+    notes?: string
+  }>
+  assumptions: string[]
+}
+
+export const createGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContext): Record<string, GitServiceApiMethod> => {
+  const defaults = ctx.defaults ?? {}
+
+  return {
+    helpActionsLogs: async (): Promise<GitServiceApiExecutionResult<GitActionsHelpBody>> => {
+      const body: GitActionsHelpBody = {
+        summary:
+          'Use actions.tasks.list to locate the failing run, then actions.jobs.logsTail to pull the last N lines of job logs.',
+        suggestedCalls: [
+          {
+            tool: 'repo.actions.tasks.list',
+            args: ['<owner>', '<repo>'],
+            options: { query: { limit: 50 } },
+            notes: 'Filter client-side by head_sha and run_number from the response.',
+          },
+          {
+            tool: 'repo.actions.jobs.logsTail',
+            args: ['<job_id>'],
+            options: { maxLines: 250 },
+            notes: 'If you have default owner/repo configured, you can pass only <job_id>.',
+          },
+          {
+            tool: 'repo.actions.jobs.logsForRunTail',
+            args: ['<head_sha>', '<run_number>'],
+            options: { maxLines: 250 },
+            notes: 'Convenience helper: resolves a run from tasks and then fetches logs (assumes run.id is job_id).',
+          },
+        ],
+        assumptions: [
+          'Gitea exposes job logs at GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs.',
+          'This helper assumes ActionTask.id can be used as job_id for the logs endpoint. If that is false in your Gitea version, use the UI to find the job_id.',
+        ],
+      }
+
+      const mapping: GitApiFeatureMapping = {
+        platform: 'GITEA',
+        featurePath: ['help', 'actionsLogs'],
+        mappedPath: ['help', 'actionsLogs'],
+        method: 'GET',
+        query: [],
+        headers: ['Accept: application/json'],
+        apiBase: buildApiBase(ctx.config.giteaHost),
+        swaggerPath: '/help/actionsLogs',
+        mapped: true,
+        reason: 'Local help content',
+      }
+
+      return {
+        mapping,
+        request: {
+          url: 'local://help/actionsLogs',
+          method: 'GET',
+          headers: {},
+          query: [],
+        },
+        response: {
+          headers: {},
+        },
+        status: 200,
+        ok: true,
+        body,
+      }
+    },
+
+    tasks: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      return requestGitea(ctx, ['actions', 'tasks', 'list'], owner, repo, 'GET', ['tasks'], parsed.options)
+    },
+
+    jobsLogs: async (...rawArgs: unknown[]) => {
+      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
+      return requestGitea(
+        ctx,
+        ['actions', 'jobs', 'logs'],
+        resolved.owner,
+        resolved.repo,
+        'GET',
+        ['jobs', resolved.id, 'logs'],
+        resolved.options,
+      )
+    },
+
+    jobsLogsTail: async (...rawArgs: unknown[]) => {
+      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
+      const result = await requestGitea(
+        ctx,
+        ['actions', 'jobs', 'logs'],
+        resolved.owner,
+        resolved.repo,
+        'GET',
+        ['jobs', resolved.id, 'logs'],
+        resolved.options,
+      )
+
+      const asText = typeof result.body === 'string' ? result.body : JSON.stringify(result.body, null, 2)
+      const tailed = tailText(asText, {
+        contains: resolved.options.contains,
+        maxLines: resolved.options.maxLines,
+        maxBytes: resolved.options.maxBytes,
+      })
+
+      return {
+        ...result,
+        body: tailed,
+      }
+    },
+
+    jobsLogsForRunTail: async (headSha: unknown, runNumber: unknown, maybeOptions?: unknown) => {
+      const sha = toTrimmedString(headSha)
+      const run = toPositiveInteger(runNumber)
+      const options = isRecord(maybeOptions) ? (maybeOptions as Record<string, unknown>) : {}
+
+      if (!sha || !run) {
+        throw new Error('headSha (string) and runNumber (positive integer) are required.')
+      }
+
+      const scope = normalizeScopeArgs(options.owner, options.repo, options)
+      const { owner, repo } = resolveOwnerRepo(scope, defaults)
+      const tasks = await requestGitea(ctx, ['actions', 'tasks', 'list'], owner, repo, 'GET', ['tasks'], scope.options)
+
+      const entries = isRecord(tasks.body) && Array.isArray(tasks.body.workflow_runs)
+        ? (tasks.body.workflow_runs as unknown[])
+        : []
+
+      const match = entries.find((entry) => {
+        if (!isRecord(entry)) return false
+        return String(entry.head_sha ?? '') === sha && Number(entry.run_number ?? NaN) === run
+      })
+
+      if (!match || !isRecord(match)) {
+        throw new Error(`No matching run found in actions/tasks for head_sha=${sha} run_number=${run}.`)
+      }
+
+      const jobId = match.id
+      const jobIdText = toTrimmedString(jobId)
+      if (!jobIdText) {
+        throw new Error('Matched run entry does not expose an id usable as job_id.')
+      }
+
+      const logs = await requestGitea(
+        ctx,
+        ['actions', 'jobs', 'logs'],
+        owner,
+        repo,
+        'GET',
+        ['jobs', jobIdText, 'logs'],
+        scope.options,
+      )
+
+      const asText = typeof logs.body === 'string' ? logs.body : JSON.stringify(logs.body, null, 2)
+      const tailed = tailText(asText, {
+        contains: scope.options.contains,
+        maxLines: scope.options.maxLines,
+        maxBytes: scope.options.maxBytes,
+      })
+
+      return {
+        ...logs,
+        body: tailed,
+      }
+    },
+
+    artifacts: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      return requestGitea(ctx, ['actions', 'artifacts', 'list'], owner, repo, 'GET', ['artifacts'], parsed.options)
+    },
+
+    artifactsByRun: async (runId: unknown, ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const id = toTrimmedString(runId)
+      if (!id) {
+        throw new Error('runId is required.')
+      }
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      return requestGitea(ctx, ['actions', 'runs', 'artifacts'], owner, repo, 'GET', ['runs', id, 'artifacts'], parsed.options)
+    },
+
+    artifactZipUrl: async (...rawArgs: unknown[]) => {
+      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
+
+      const result = await requestGitea(
+        ctx,
+        ['actions', 'artifacts', 'downloadZipUrl'],
+        resolved.owner,
+        resolved.repo,
+        'GET',
+        ['artifacts', resolved.id, 'zip'],
+        resolved.options,
+        { redirect: 'manual' },
+      )
+
+      const location =
+        typeof (result.response.headers.location) === 'string'
+          ? result.response.headers.location
+          : typeof (result.response.headers['location']) === 'string'
+            ? result.response.headers['location']
+            : null
+
+      return {
+        ...result,
+        body: {
+          status: result.status,
+          location,
+        },
+      }
+    },
+  }
+}
+
+const ensureNamespace = (root: GitServiceApi, path: string[]): GitServiceApi => {
+  let cursor: GitServiceApi = root
+  for (const segment of path) {
+    const current = cursor[segment]
+    if (!isRecord(current)) {
+      cursor[segment] = {}
+    }
+    cursor = cursor[segment] as GitServiceApi
+  }
+  return cursor
+}
+
+export const attachGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContext): void => {
+  const methods = createGitActionsApi(api, ctx)
+  const targets = [
+    ensureNamespace(api, ['actions']),
+    ensureNamespace(api, ['repo', 'actions']),
+    ensureNamespace(api, ['help']),
+    ensureNamespace(api, ['repo', 'help']),
+  ]
+
+  const mapping: Record<string, { to: string; description: string }> = {
+    helpActionsLogs: { to: 'actionsLogs', description: 'Help for fetching Gitea Actions job logs' },
+    tasks: { to: 'tasks.list', description: 'List repository action tasks (workflow runs)' },
+    jobsLogs: { to: 'jobs.logs', description: 'Download job logs for a workflow run job_id' },
+    jobsLogsTail: { to: 'jobs.logsTail', description: 'Download and tail job logs (bounded for LLM)' },
+    jobsLogsForRunTail: { to: 'jobs.logsForRunTail', description: 'Resolve run by sha+run_number and tail logs' },
+    artifacts: { to: 'artifacts.list', description: 'List repository artifacts' },
+    artifactsByRun: { to: 'runs.artifacts', description: 'List artifacts for a run' },
+    artifactZipUrl: { to: 'artifacts.downloadZipUrl', description: 'Return redirect URL for artifact zip download' },
+  }
+
+  for (const target of targets) {
+    for (const [name, method] of Object.entries(methods)) {
+      const exportName = mapping[name]?.to ?? name
+      if (!(exportName in target)) {
+        target[exportName] = method
+      }
+    }
+  }
+}
+

package/src/git-service-api.ts

@@ -3,6 +3,7 @@ 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 { spawn } from 'node:child_process'
 import crypto from 'node:crypto'
 
@@ -41,7 +42,10 @@ export type GitServiceApi = {
 
 type ApiCallOptions = {
   method?: string
-  body?: unknown
+  requestBody?: unknown
+  requestJson?: unknown
+  requestData?: unknown
+  requestPayload?: unknown
   json?: unknown
   data?: unknown
   payload?: unknown
@@ -134,7 +138,18 @@ const mapFlagValues = (
     alias.set(canonical, flag.name)
   }
 
-  const reserved = new Set(['body', 'json', 'data', 'payload', 'headers', 'query', 'method'])
+  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)
@@ -164,30 +179,28 @@ const mapFlagValues = (
 const buildRequestBody = (
   method: string,
   options: Record<string, unknown>,
-  unmappedOptions: Record<string, unknown>,
+  defaultBody: Record<string, unknown>,
 ): unknown | undefined => {
-  if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(method.toUpperCase())) {
-    return undefined
-  }
-
-  if (options.body !== undefined) {
-    return options.body
-  }
-
-  if (options.json !== undefined) {
-    return options.json
-  }
+  const normalizedMethod = method.toUpperCase()
+  const explicit =
+    options.requestBody ??
+    options.requestJson ??
+    options.requestData ??
+    options.requestPayload ??
+    options.json ??
+    options.data ??
+    options.payload
 
-  if (options.data !== undefined) {
-    return options.data
+  if (explicit !== undefined) {
+    return explicit
   }
 
-  if (options.payload !== undefined) {
-    return options.payload
+  if (!['POST', 'PUT', 'PATCH'].includes(normalizedMethod)) {
+    return undefined
   }
 
-  if (Object.keys(unmappedOptions).length > 0) {
-    return unmappedOptions
+  if (Object.keys(defaultBody).length > 0) {
+    return defaultBody
   }
 
   return undefined
@@ -240,6 +253,48 @@ const canUseAbortSignalTimeout = (): boolean =>
 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') {
@@ -364,17 +419,33 @@ const createMethod = (
 ): GitServiceApiMethod => {
   return async (...rawArgs: unknown[]) => {
     const { args, options } = splitArgsAndOptions(rawArgs)
-    const { flags, unhandled } = mapFlagValues(feature, options)
     const { query: additionalQuery, method: methodOverride, ...bodyOptions } = (options as ApiCallOptions)
 
-    const mapping = await adapter.mapFeature({
+    const baseMapping = await adapter.mapFeature({
       feature,
       args,
-      flagValues: flags,
+      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 = mapping.mappedPath.map((segment) => {
+    const hydratedPath = resolvedMapping.mappedPath.map((segment) => {
       if (segment === '{owner}' && defaults.defaultOwner) {
         return defaults.defaultOwner
       }
@@ -387,9 +458,13 @@ const createMethod = (
     })
     assertResolvedMappedPath(hydratedPath, feature.path)
 
-    const requestBody = buildRequestBody(mapping.method, bodyOptions, unhandled)
+    const requestBody = buildRequestBody(
+      resolvedMapping.method,
+      bodyOptions,
+      normalizedMethod === 'GET' ? {} : buildDefaultWriteBody(options),
+    )
     const headers = {
-      ...toHeaderRecord(mapping.headers),
+      ...toHeaderRecord(resolvedMapping.headers),
       ...(options.headers ?? {}),
     }
 
@@ -397,15 +472,15 @@ const createMethod = (
       headers['Content-Type'] = 'application/json'
     }
 
-    const requestUrl = buildUrl(mapping.apiBase, hydratedPath, mapping.query, additionalQuery ?? {})
+    const requestUrl = buildUrl(resolvedMapping.apiBase, hydratedPath, resolvedMapping.query, mergedQuery)
     const requestInit: RequestInit = {
-      method: mapping.method,
+      method: resolvedMapping.method,
       headers,
       body: requestBody !== undefined ? JSON.stringify(requestBody) : undefined,
     }
 
     const startedAt = Date.now()
-    log?.(`http:request ${mapping.method} ${requestUrl}`)
+    log?.(`http:request ${resolvedMapping.method} ${requestUrl}`)
     try {
       const responseHeaders: Record<string, string> = {}
       let status = 0
@@ -416,7 +491,7 @@ const createMethod = (
         const curlResult = await callCurl(
           requestUrl,
           {
-            method: mapping.method,
+            method: resolvedMapping.method,
             headers,
             ...(requestInit.body !== undefined ? { body: String(requestInit.body) } : {}),
           },
@@ -465,7 +540,7 @@ const createMethod = (
           }
         } catch (error) {
           if ((timeoutSignal && timeoutSignal.aborted) || controller?.signal.aborted) {
-            throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${mapping.method} ${requestUrl}`)
+            throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${resolvedMapping.method} ${requestUrl}`)
           }
           throw error
         } finally {
@@ -475,17 +550,17 @@ const createMethod = (
         }
       }
 
-      log?.(`http:response ${mapping.method} ${requestUrl} -> ${status} (${Date.now() - startedAt}ms)`)
+      log?.(`http:response ${resolvedMapping.method} ${requestUrl} -> ${status} (${Date.now() - startedAt}ms)`)
       return {
         mapping: {
-          ...mapping,
+          ...resolvedMapping,
           mappedPath: hydratedPath,
         },
         request: {
           url: requestUrl,
-          method: mapping.method,
+          method: resolvedMapping.method,
           headers,
-          query: [...mapping.query],
+          query: [...resolvedMapping.query],
           body: requestBody,
         },
         response: {
@@ -575,6 +650,12 @@ export const createGitServiceApi = (options: GitServiceApiFactoryOptions = {}):
   }
 
   attachGitLabelManagementApi(root, defaults)
+  attachGitActionsApi(root, {
+    config,
+    defaults,
+    requestTimeoutMs,
+    log,
+  })
 
   return root
 }

package/src/index.ts

@@ -44,6 +44,7 @@ export {
   type GitLabelManagementDefaults,
   type GitRepositoryLabel,
 } from './label-management'
+export { attachGitActionsApi, createGitActionsApi, type GitActionsApiContext, type GitActionsApiDefaults, type GitActionsHelpBody } from './actions-api'
 export { resolveProjectRepoIdentity, type GitRepositoryIdentity } from './repository'
 export type {
   GitServiceApi,

package/src/platform/gitea-rules.ts

@@ -82,6 +82,9 @@ export const EXACT_GITEA_RULES: GiteaRouteRule[] = [
   rule(['workflow', 'run'], 'POST', '/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches'),
   rule(['workflow', 'view'], 'GET', '/repos/{owner}/{repo}/actions/workflows/{workflow_id}'),
 
+  // Run commands (Gitea Actions tasks list is the closest analogue)
+  rule(['run', 'list'], 'GET', '/repos/{owner}/{repo}/actions/tasks', 'maps run.list to action task list'),
+
   // Secret and variable commands
   rule(['secret', 'delete'], 'DELETE', '/repos/{owner}/{repo}/actions/secrets/{secretname}'),
   rule(['secret', 'list'], 'GET', '/repos/{owner}/{repo}/actions/secrets'),
@@ -112,7 +115,6 @@ export const DEFAULT_GITEA_FIRST_TOKEN_RULES = new Map<string, GiteaRouteRule>([
   ['pr', rule(['pr'], 'GET', '/repos/{owner}/{repo}/pulls', 'fallback to pull request list')],
   ['repo', rule(['repo'], 'GET', '/repos/{owner}/{repo}', 'fallback to repository read')],
   ['release', rule(['release'], 'GET', '/repos/{owner}/{repo}/releases', 'fallback to release list')],
-  ['run', rule(['run'], 'GET', '/repos/{owner}/{repo}/actions/tasks', 'fallback to workflow task list')],
   ['workflow', rule(['workflow'], 'GET', '/repos/{owner}/{repo}/actions/workflows', 'fallback to workflow list')],
   ['search', rule(['search'], 'GET', '/repos/search', 'fallback to global repo search')],
   ['secret', rule(['secret'], 'GET', '/repos/{owner}/{repo}/actions/secrets', 'fallback to repository secret list')],