@foundation0/git 1.2.3 → 1.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundation0/git",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "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
+      }
+    }
+  }
+}
+