@foundation0/git 1.2.5 → 1.3.0

package/mcp/README.md

@@ -231,7 +231,7 @@ Tips:
   `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`
+  `repo.actions.diagnoseLatestFailure`, and `repo.actions.artifacts.downloadZipUrl`
 - Includes a discovery helper:
   `help.actionsLogs` (also available under `repo.help.actionsLogs`)
 
@@ -248,3 +248,19 @@ Tips:
   "maxLines": 250
 }
 ```
+
+## Notes: actions.diagnoseLatestFailure
+
+`repo.actions.diagnoseLatestFailure` is a convenience tool that finds the most recent failing Actions task and returns a log tail.
+
+```json
+{ "owner": "F0", "repo": "adl", "workflowName": "TypeScript", "maxLines": 250 }
+```
+
+## Notes: actions.runs.artifacts
+
+`repo.actions.runs.artifacts` accepts a named form to avoid legacy positional ordering:
+
+```json
+{ "owner": "F0", "repo": "adl", "runId": 11 }
+```

package/mcp/src/server.ts

@@ -363,6 +363,9 @@ const buildToolName = (tool: ToolDefinition, prefix?: string): string =>
   prefix ? `${prefix}.${tool.name}` : tool.name
 
 const isLogsForRunTailTool = (toolName: string): boolean => toolName.endsWith('jobs.logsForRunTail')
+const isArtifactsByRunTool = (toolName: string): boolean => toolName.endsWith('runs.artifacts')
+const isDiagnoseLatestFailureTool = (toolName: string): boolean =>
+  toolName.endsWith('diagnoseLatestFailure') && toolName.includes('.actions.')
 
 const buildGenericToolSchema = (): Record<string, unknown> => ({
   type: 'object',
@@ -386,6 +389,49 @@ const buildGenericToolSchema = (): Record<string, unknown> => ({
   },
 })
 
+const buildArtifactsByRunSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    runId: {
+      description: 'Workflow run id (alias: run_id).',
+      anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }],
+    },
+    run_id: {
+      description: 'Alias for runId.',
+      anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }],
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    // Legacy positional forms:
+    // - Preferred by humans/LLMs: [owner, repo, runId]
+    // - Back-compat with the underlying helper signature: [runId, owner, repo]
+    args: {
+      type: 'array',
+      items: {},
+      description:
+        'Legacy positional form. Prefer named params. If used, pass [owner, repo, runId] (recommended) or the legacy [runId, owner, repo]. You can also pass only [runId] if defaults are configured.',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Options object (query/headers/body payload). Extra top-level keys are merged into options.',
+    },
+  },
+  anyOf: [{ required: ['runId'] }, { required: ['run_id'] }, { required: ['args'] }],
+})
+
 const buildLogsForRunTailSchema = (): Record<string, unknown> => ({
   type: 'object',
   additionalProperties: true,
@@ -459,8 +505,67 @@ const buildLogsForRunTailSchema = (): Record<string, unknown> => ({
   ],
 })
 
+const buildDiagnoseLatestFailureSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    workflowName: {
+      type: 'string',
+      description: 'Optional filter: match failing runs by name/display_title (case-insensitive substring).',
+    },
+    limit: {
+      type: 'integer',
+      minimum: 1,
+      description: 'How many tasks/runs to fetch before filtering (default: 50).',
+    },
+    maxLines: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max lines to return from the end of the logs (default: 200).',
+    },
+    maxBytes: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max bytes to return from the end of the logs.',
+    },
+    contains: {
+      type: 'string',
+      description: 'If set, only return log lines containing this substring.',
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Legacy positional form: [owner, repo] plus options.workflowName/maxLines/etc.',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Options object. Extra top-level keys are merged into options.',
+    },
+  },
+})
+
 const buildToolInputSchema = (tool: ToolDefinition): Record<string, unknown> =>
-  isLogsForRunTailTool(tool.name) ? buildLogsForRunTailSchema() : buildGenericToolSchema()
+  isLogsForRunTailTool(tool.name)
+    ? buildLogsForRunTailSchema()
+    : isArtifactsByRunTool(tool.name)
+      ? buildArtifactsByRunSchema()
+      : isDiagnoseLatestFailureTool(tool.name)
+        ? buildDiagnoseLatestFailureSchema()
+      : buildGenericToolSchema()
 
 const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?: string) => {
   const toolNames = tools.map((tool) => ({
@@ -544,15 +649,67 @@ const invokeTool = async (
   return tool.method(...invocationArgs)
 }
 
+const pickArgsFromNormalizedPayload = (normalized: unknown, record: Record<string, unknown>): unknown[] => {
+  if (Array.isArray(normalized)) {
+    return normalized
+  }
+  return Array.isArray(record.args) ? record.args : []
+}
+
+const pickNestedRecord = (value: unknown): Record<string, unknown> => (isRecord(value) ? (value as Record<string, unknown>) : {})
+
+const normalizeQueryRecord = (query: unknown): Record<string, unknown> => {
+  if (isRecord(query)) {
+    return query
+  }
+
+  if (!Array.isArray(query)) {
+    return {}
+  }
+
+  const merged: Record<string, unknown> = {}
+
+  for (const entry of query) {
+    if (!isRecord(entry)) continue
+
+    const name = typeof entry.name === 'string' ? entry.name.trim() : ''
+    if (name) {
+      merged[name] = entry.value
+      continue
+    }
+
+    // Support [{ headSha: "..." }, { runNumber: 11 }] style arrays.
+    for (const [key, value] of Object.entries(entry)) {
+      if (value !== undefined) merged[key] = value
+    }
+  }
+
+  return merged
+}
+
 const invokeLogsForRunTailTool = async (tool: ToolDefinition, payload: unknown): Promise<GitServiceApiExecutionResult> => {
   const normalized = normalizeArgumentPayload(payload)
   const record = isRecord(normalized) ? normalized : {}
-  const args = Array.isArray(record.args) ? record.args : []
+  const args = pickArgsFromNormalizedPayload(normalized, record)
   const options = pickRecord(record.options)
-
-  const headShaNamed = toTrimmedString(pickFirst(record.headSha, record.head_sha, options.headSha, options.head_sha))
+  const query = normalizeQueryRecord(options.query)
+  const data = pickNestedRecord(options.data)
+
+  const headShaNamed = toTrimmedString(
+    pickFirst(
+      record.headSha,
+      record.head_sha,
+      options.headSha,
+      options.head_sha,
+      query.headSha,
+      query.head_sha,
+      data.headSha,
+      data.head_sha,
+    ),
+  )
   const runNumberNamed = pickFirst(
     toPositiveInteger(pickFirst(record.runNumber, record.run_number, options.runNumber, options.run_number)),
+    toPositiveInteger(pickFirst(query.runNumber, query.run_number, data.runNumber, data.run_number)),
     null,
   )
 
@@ -570,20 +727,28 @@ const invokeLogsForRunTailTool = async (tool: ToolDefinition, payload: unknown):
   const ownerFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[0]) : ''
   const repoFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[1]) : ''
 
-  const owner = toTrimmedString(pickFirst(record.owner, options.owner, ownerFromArgs)) || undefined
-  const repo = toTrimmedString(pickFirst(record.repo, options.repo, repoFromArgs)) || undefined
+  const owner =
+    toTrimmedString(pickFirst(record.owner, options.owner, query.owner, data.owner, ownerFromArgs)) || undefined
+  const repo = toTrimmedString(pickFirst(record.repo, options.repo, query.repo, data.repo, repoFromArgs)) || undefined
 
   const sha = toTrimmedString(pickFirst(headShaNamed || null, headShaPositional || null)) || ''
   const run = pickFirst(runNumberNamed, runNumberPositional) ?? null
 
   if (!sha || !run) {
     throw new Error(
-      'headSha (string) and runNumber (positive integer) are required. Preferred invocation: { owner, repo, headSha, runNumber, maxLines }.',
+      'headSha (string) and runNumber (positive integer) are required. Preferred invocation: { owner, repo, headSha, runNumber, maxLines }. (Compatibility: options.query.{headSha,runNumber} is also accepted.)',
     )
   }
 
+  const containsFromQuery = typeof query.contains === 'string' ? query.contains : undefined
+  const maxLinesFromQuery = toPositiveInteger(query.maxLines)
+  const maxBytesFromQuery = toPositiveInteger(query.maxBytes)
+
   const cleanedOptions = stripMcpOnlyOptions({
     ...options,
+    ...(containsFromQuery ? { contains: containsFromQuery } : {}),
+    ...(maxLinesFromQuery ? { maxLines: maxLinesFromQuery } : {}),
+    ...(maxBytesFromQuery ? { maxBytes: maxBytesFromQuery } : {}),
     ...(owner ? { owner } : {}),
     ...(repo ? { repo } : {}),
   })
@@ -591,6 +756,57 @@ const invokeLogsForRunTailTool = async (tool: ToolDefinition, payload: unknown):
   return tool.method(sha, run, cleanedOptions)
 }
 
+const invokeArtifactsByRunTool = async (
+  tool: ToolDefinition,
+  payload: unknown,
+): Promise<GitServiceApiExecutionResult> => {
+  const normalized = normalizeArgumentPayload(payload)
+  const record = isRecord(normalized) ? normalized : {}
+  const args = pickArgsFromNormalizedPayload(normalized, record)
+  const options = pickRecord(record.options)
+
+  const runIdNamed = toTrimmedString(pickFirst(record.runId, record.run_id, options.runId, options.run_id)) || ''
+
+  const a0 = args.length >= 1 ? toTrimmedString(args[0]) : ''
+  const a1 = args.length >= 2 ? toTrimmedString(args[1]) : ''
+  const a2 = args.length >= 3 ? toTrimmedString(args[2]) : ''
+
+  // Heuristic:
+  // - If named runId is set, use it.
+  // - Else if args look like [owner, repo, runId], use that.
+  // - Else treat args as legacy [runId, owner, repo] (or [runId] with defaults).
+  const shouldTreatAsOwnerRepoRunId = Boolean(a0) && Boolean(a1) && Boolean(a2) && !runIdNamed
+
+  const owner =
+    toTrimmedString(pickFirst(record.owner, options.owner, shouldTreatAsOwnerRepoRunId ? a0 : a1)) || undefined
+  const repo =
+    toTrimmedString(pickFirst(record.repo, options.repo, shouldTreatAsOwnerRepoRunId ? a1 : a2)) || undefined
+  const runId = toTrimmedString(pickFirst(runIdNamed || null, shouldTreatAsOwnerRepoRunId ? a2 : a0)) || ''
+
+  if (!runId) {
+    throw new Error('runId is required. Preferred invocation: { owner, repo, runId }.')
+  }
+
+  const cleanedOptions = stripMcpOnlyOptions({
+    ...options,
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+  })
+
+  // Underlying helper signature is (runId, owner?, repo?, options?).
+  // We always pass runId first, and owner/repo if we have them.
+  if (owner && repo) {
+    return tool.method(runId, owner, repo, cleanedOptions)
+  }
+
+  if (owner && !repo) {
+    // Unusual: allow passing only owner explicitly.
+    return tool.method(runId, owner, cleanedOptions)
+  }
+
+  return tool.method(runId, cleanedOptions)
+}
+
 export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpServerInstance => {
   const api = createGitServiceApi(options)
   const tools = collectGitTools(api)
@@ -650,6 +866,8 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
 
               const data = await (isLogsForRunTailTool(toolDefinition.name)
                 ? invokeLogsForRunTailTool(toolDefinition, mergedPayload)
+                : isArtifactsByRunTool(toolDefinition.name)
+                  ? invokeArtifactsByRunTool(toolDefinition, mergedPayload)
                 : invokeTool(toolDefinition, mergedPayload))
 
               const { isError, envelope } = toMcpEnvelope(data, effectiveFormat)
@@ -705,6 +923,8 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
       const controls = extractOutputControls(request.params.arguments)
       const result = await (isLogsForRunTailTool(tool.name)
         ? invokeLogsForRunTailTool(tool, request.params.arguments)
+        : isArtifactsByRunTool(tool.name)
+          ? invokeArtifactsByRunTool(tool, request.params.arguments)
         : invokeTool(tool, request.params.arguments))
 
       const { isError, envelope } = toMcpEnvelope(result, controls.format ?? 'terse')

package/package.json

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

package/src/actions-api.ts

@@ -9,9 +9,25 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
 
 const toTrimmedString = (value: unknown): string | null => {
+  if (value === null || value === undefined) {
+    return null
+  }
+
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return null
+    const asText = String(Math.trunc(value)).trim()
+    return asText.length > 0 ? asText : null
+  }
+
+  if (typeof value === 'bigint') {
+    const asText = value.toString().trim()
+    return asText.length > 0 ? asText : null
+  }
+
   if (typeof value !== 'string') {
     return null
   }
+
   const trimmed = value.trim()
   return trimmed.length > 0 ? trimmed : null
 }
@@ -162,6 +178,19 @@ const resolveOwnerRepoFromArgs = (
   return { ...resolved, rest: args }
 }
 
+type NormalizedActionsState = 'success' | 'failure' | 'pending'
+
+const normalizeActionsState = (raw: unknown): NormalizedActionsState => {
+  const value = toTrimmedString(raw).toLowerCase()
+  if (value === 'success') return 'success'
+  if (value === 'failure' || value === 'failed' || value === 'error') return 'failure'
+  if (value === 'cancelled' || value === 'canceled') return 'failure'
+  if (value === 'skipped') return 'success'
+  if (value === 'running' || value === 'in_progress' || value === 'queued' || value === 'waiting') return 'pending'
+  if (value === 'pending') return 'pending'
+  return 'pending'
+}
+
 const resolveOwnerRepoAndId = (
   rawArgs: unknown[],
   defaults: GitActionsApiDefaults,
@@ -495,10 +524,24 @@ export const createGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContex
         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)
+      const jobIdCandidate =
+        (match as Record<string, unknown>).job_id ??
+        (match as Record<string, unknown>).jobId ??
+        (match as Record<string, unknown>).task_id ??
+        (match as Record<string, unknown>).taskId ??
+        (match as Record<string, unknown>).id
+
+      const jobIdText = toTrimmedString(jobIdCandidate)
       if (!jobIdText) {
-        throw new Error('Matched run entry does not expose an id usable as job_id.')
+        const keys = Object.keys(match).slice(0, 32).join(',')
+        const preview = (() => {
+          try {
+            return JSON.stringify(match).slice(0, 500)
+          } catch {
+            return ''
+          }
+        })()
+        throw new Error(`Matched run entry does not expose an id usable as job_id. keys=[${keys}] preview=${preview}`)
       }
 
       const logs = await requestGitea(
@@ -524,6 +567,109 @@ export const createGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContex
       }
     },
 
+    diagnoseLatestFailure: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      // Allow calling with a single object payload: { owner, repo, workflowName, ... }.
+      const scope = normalizeScopeArgs(parsed.options.owner, parsed.options.repo, parsed.options)
+      const { owner, repo } = resolveOwnerRepo(scope, defaults)
+
+      const workflowNameRaw = typeof scope.options.workflowName === 'string' ? scope.options.workflowName.trim() : ''
+      const workflowName = workflowNameRaw.length > 0 ? workflowNameRaw : null
+      const maxLines = toPositiveInteger(scope.options.maxLines) ?? DEFAULT_LOG_TAIL_LINES
+      const maxBytes = toPositiveInteger(scope.options.maxBytes)
+      const contains = typeof scope.options.contains === 'string' ? scope.options.contains : undefined
+      const limit = toPositiveInteger(scope.options.limit) ?? 50
+
+      const tasks = await requestGitea(
+        ctx,
+        ['actions', 'tasks', 'list'],
+        owner,
+        repo,
+        'GET',
+        ['tasks'],
+        { ...scope.options, query: { ...(isRecord(scope.options.query) ? scope.options.query : {}), limit } },
+      )
+
+      const entries = isRecord(tasks.body) && Array.isArray(tasks.body.workflow_runs)
+        ? (tasks.body.workflow_runs as unknown[])
+        : []
+
+      const normalizedWorkflowName = workflowName ? workflowName.toLowerCase() : null
+      const failing = entries
+        .filter((entry) => isRecord(entry))
+        .filter((entry) => normalizeActionsState((entry as Record<string, unknown>).status) === 'failure')
+        .filter((entry) => {
+          if (!normalizedWorkflowName) return true
+          const name = String((entry as Record<string, unknown>).name ?? '').toLowerCase()
+          const displayTitle = String((entry as Record<string, unknown>).display_title ?? '').toLowerCase()
+          return name.includes(normalizedWorkflowName) || displayTitle.includes(normalizedWorkflowName)
+        })
+        .sort((a, b) => {
+          const aRecord = a as Record<string, unknown>
+          const bRecord = b as Record<string, unknown>
+          const aUpdated = Date.parse(String(aRecord.updated_at ?? '')) || 0
+          const bUpdated = Date.parse(String(bRecord.updated_at ?? '')) || 0
+          return bUpdated - aUpdated
+        })
+
+      const match = failing[0]
+      if (!match || !isRecord(match)) {
+        throw new Error(
+          workflowName
+            ? `No failing workflow run found matching workflowName=${workflowName}.`
+            : 'No failing workflow run found.',
+        )
+      }
+
+      const sha = String((match as Record<string, unknown>).head_sha ?? '').trim()
+      const run = toPositiveInteger((match as Record<string, unknown>).run_number)
+      if (!sha || !run) {
+        throw new Error('Matched run entry is missing head_sha or run_number.')
+      }
+
+      const jobIdCandidate =
+        (match as Record<string, unknown>).job_id ??
+        (match as Record<string, unknown>).jobId ??
+        (match as Record<string, unknown>).task_id ??
+        (match as Record<string, unknown>).taskId ??
+        (match as Record<string, unknown>).id
+
+      const jobIdText = toTrimmedString(jobIdCandidate)
+      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,
+        maxLines,
+        ...(maxBytes ? { maxBytes } : {}),
+      })
+
+      return {
+        ...logs,
+        body: {
+          run: match,
+          logsTail: tailed,
+          owner,
+          repo,
+          headSha: sha,
+          runNumber: run,
+          jobId: jobIdText,
+        },
+      }
+    },
+
     artifacts: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
       const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
       const { owner, repo } = resolveOwnerRepo(parsed, defaults)
@@ -599,6 +745,7 @@ export const attachGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContex
     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' },
+    diagnoseLatestFailure: { to: 'diagnoseLatestFailure', description: 'Find latest failing run and return log tail' },
     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' },
@@ -613,4 +760,3 @@ export const attachGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContex
     }
   }
 }
-