Add failed test and log cleanup tools

Author: backslash-f

README.md

@@ -17,9 +17,12 @@ Minimal MCP server for discovering Xcode Cloud products and workflows, then retr
 - List recent workflow runs with `list_build_runs`.
 - Retrieve build issue counts with `get_build_issues`.
 - Retrieve and summarize text-like build logs with `get_build_logs`.
+- Materialize build logs into a local temp directory with `materialize_build_logs`.
 - Save extracted logs to a local temporary directory and return file paths for agent-side inspection.
 - Retrieve test summaries with `get_test_results`.
+- Retrieve only detected failed tests with `get_failed_tests`.
 - Retrieve screenshots, videos, result bundles, and test products with `get_test_artifacts`.
+- Clean up saved local log directories with `cleanup_saved_logs`.
 
 Build lookup is workflow-scoped. Retrieval tools accept a direct `buildRunId`, or a `workflowId` plus `buildNumber`, or a `workflowId` plus `buildSelector: "latest" | "latestFailing"`.
 
@@ -71,8 +74,11 @@ codex mcp add xcode-cloud \
 - `list_build_runs(workflowId, limit?, status?)`
 - `get_build_issues(buildRunId? workflowId? buildNumber? buildSelector?)`
 - `get_build_logs(buildRunId? workflowId? buildNumber? buildSelector?, maxCharacters?)`
+- `materialize_build_logs(buildRunId? workflowId? buildNumber? buildSelector?)`
 - `get_test_results(buildRunId? workflowId? buildNumber? buildSelector?)`
+- `get_failed_tests(buildRunId? workflowId? buildNumber? buildSelector?)`
 - `get_test_artifacts(buildRunId? workflowId? buildNumber? buildSelector?)`
+- `cleanup_saved_logs(buildRunId?, maxAgeHours?)`
 
 ## Log Retrieval Behavior
 
@@ -83,6 +89,13 @@ codex mcp add xcode-cloud \
 - it returns a compact `failedTests` summary, `highlights`, and a capped `excerpt`
 - even if a caller passes a very large `maxCharacters`, the inline excerpt is clamped to avoid oversized MCP responses
 
+Recommended agent workflow:
+
+1. Call `get_failed_tests` or `get_build_logs`.
+2. Read `savedLogsDirectory`.
+3. Use `rg` inside that directory to inspect the exact failing test or assertion.
+4. If needed, call `cleanup_saved_logs` when the investigation is done.
+
 Temporary logs are written under the system temp directory in a path like:
 
 ```text
@@ -94,8 +107,8 @@ On macOS this typically resolves to a path under `/var/folders/.../T/`.
 Cleanup policy:
 
 - each new call for the same `buildRunId` deletes and recreates that build-specific temp directory first
-- older build directories are not explicitly garbage-collected by the server yet
-- they are left in the system temp area, where the OS may eventually clean them up
+- older build directories are pruned automatically when they are older than 24 hours
+- you can also call `cleanup_saved_logs` directly for one `buildRunId` or for all directories older than a chosen retention window
 
 ## Example Prompts
 
@@ -107,6 +120,10 @@ Retrieve logs of the latest failing build for workflow abc123.
 Retrieve logs of build 81, then inspect the returned savedLogsDirectory and grep for Expectation failed.
 ```
 
+```text
+Get the failed tests for build 81, then open the saved logs directory and inspect the failing test in context.
+```
+
 ```text
 Retrieve logs of build number 42 for workflow abc123.
 ```

src/tools/results.ts

@@ -8,7 +8,11 @@ import {
 } from '../utils/build-locator.js';
 import { collectBuildRunArtifacts } from '../utils/build-artifacts.js';
 import { summarizeLogTexts } from '../utils/log-analysis.js';
-import { storeLogArtifacts } from '../utils/log-storage.js';
+import {
+  cleanupSavedLogs,
+  removeSavedLogsForBuildRun,
+  storeLogArtifacts,
+} from '../utils/log-storage.js';
 import { errorResponse, jsonResponse } from '../utils/tool-response.js';
 
 interface BuildLookupInput {
@@ -87,6 +91,68 @@ export function registerResultTools(
       }
     },
   );
+
+  server.registerTool(
+    'materialize_build_logs',
+    {
+      description:
+        'Resolve a build, download and extract text-like log artifacts into a local temporary directory, and return saved file paths for grep or cat based investigation.',
+      inputSchema: buildLookupSchema(),
+    },
+    async (input: BuildLookupInput) => {
+      try {
+        const buildRun = await resolveBuildLocator(client, input);
+        const groupedArtifacts = await collectBuildRunArtifacts(client, buildRun.id);
+        const storedLogs = await storeLogArtifacts(
+          client,
+          buildRun.id,
+          groupedArtifacts.logs,
+        );
+
+        return jsonResponse({
+          buildRun: formatBuildRun(buildRun),
+          artifacts: groupedArtifacts.logs.map(formatArtifact),
+          savedLogsDirectory: storedLogs.directoryPath,
+          savedLogs: storedLogs.savedLogFiles,
+        });
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'cleanup_saved_logs',
+    {
+      description:
+        'Remove saved local log directories either for one build run or for all directories older than a retention window.',
+      inputSchema: {
+        buildRunId: z.string().optional(),
+        maxAgeHours: z.number().positive().max(24 * 30).optional(),
+      },
+    },
+    async ({
+      buildRunId,
+      maxAgeHours,
+    }: {
+      buildRunId?: string;
+      maxAgeHours?: number;
+    }) => {
+      try {
+        if (buildRunId) {
+          const cleanupResult = await removeSavedLogsForBuildRun(buildRunId);
+
+          return jsonResponse(cleanupResult);
+        }
+
+        const cleanupResult = await cleanupSavedLogs({ maxAgeHours });
+
+        return jsonResponse(cleanupResult);
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
 }
 
 function buildLookupSchema() {

src/tools/tests.ts

@@ -75,6 +75,41 @@ export function registerTestTools(
     },
   );
 
+  server.registerTool(
+    'get_failed_tests',
+    {
+      description:
+        'Resolve a build, ensure logs are materialized locally, and return only the detected failed tests with their assertion messages when available.',
+      inputSchema: buildLookupSchema(),
+    },
+    async (input: BuildLookupInput) => {
+      try {
+        const buildRun = await resolveBuildLocator(client, input);
+        const groupedArtifacts = await collectBuildRunArtifacts(client, buildRun.id);
+        const storedLogs = await storeLogArtifacts(
+          client,
+          buildRun.id,
+          groupedArtifacts.logs,
+        );
+        const logSummary = summarizeLogTexts(storedLogs.parsedLogTexts, 1500);
+
+        return jsonResponse({
+          buildRun: {
+            id: buildRun.id,
+            number: buildRun.attributes.number,
+            workflowId: buildRun.relationships?.workflow?.data.id,
+            completionStatus: buildRun.attributes.completionStatus,
+          },
+          savedLogsDirectory: storedLogs.directoryPath,
+          savedLogs: storedLogs.savedLogFiles,
+          failedTests: logSummary.failedTests,
+        });
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+
   server.registerTool(
     'get_test_artifacts',
     {

src/utils/log-storage.ts

@@ -1,4 +1,4 @@
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import type { AppStoreConnectClient } from '../api/client.js';
@@ -19,15 +19,36 @@ export interface StoredLogs {
   savedLogFiles: SavedLogFile[];
 }
 
+const DEFAULT_LOG_RETENTION_HOURS = 24;
+
+/**
+ * Return the root directory used for materialized log files.
+ */
+export function getSavedLogsRootDirectory(
+  baseDirectory: string = tmpdir(),
+): string {
+  return path.join(baseDirectory, 'xcode-cloud-mcp', 'build-logs');
+}
+
 /**
  * Download log artifacts, persist them locally, and return extracted text when available.
  */
 export async function storeLogArtifacts(
   client: AppStoreConnectClient,
   buildRunId: string,
   artifacts: CiArtifact[],
+  options?: {
+    baseDirectory?: string;
+    retentionHours?: number;
+  },
 ): Promise<StoredLogs> {
-  const directoryPath = path.join(tmpdir(), 'xcode-cloud-mcp', 'build-logs', buildRunId);
+  const rootDirectory = getSavedLogsRootDirectory(options?.baseDirectory);
+  await cleanupSavedLogs({
+    rootDirectory,
+    maxAgeHours: options?.retentionHours ?? DEFAULT_LOG_RETENTION_HOURS,
+  });
+
+  const directoryPath = path.join(rootDirectory, buildRunId);
   await rm(directoryPath, { recursive: true, force: true });
   await mkdir(directoryPath, { recursive: true });
 
@@ -82,3 +103,92 @@ export async function storeLogArtifacts(
 function sanitizeFileName(fileName: string): string {
   return fileName.replace(/[\\/:\s]+/g, '-');
 }
+
+/**
+ * Remove materialized logs for one build run.
+ */
+export async function removeSavedLogsForBuildRun(
+  buildRunId: string,
+  options?: {
+    baseDirectory?: string;
+  },
+): Promise<{ removedDirectory: string; removed: boolean }> {
+  const directoryPath = path.join(
+    getSavedLogsRootDirectory(options?.baseDirectory),
+    buildRunId,
+  );
+
+  const removed = await removeDirectoryIfPresent(directoryPath);
+
+  return {
+    removedDirectory: directoryPath,
+    removed,
+  };
+}
+
+/**
+ * Remove old materialized log directories under the saved logs root.
+ */
+export async function cleanupSavedLogs(options?: {
+  rootDirectory?: string;
+  baseDirectory?: string;
+  maxAgeHours?: number;
+}): Promise<{
+  rootDirectory: string;
+  removedDirectories: string[];
+}> {
+  const rootDirectory =
+    options?.rootDirectory ??
+    getSavedLogsRootDirectory(options?.baseDirectory);
+  const maxAgeHours = options?.maxAgeHours ?? DEFAULT_LOG_RETENTION_HOURS;
+  const maxAgeMilliseconds = Math.max(1, maxAgeHours) * 60 * 60 * 1000;
+  const removedDirectories: string[] = [];
+
+  try {
+    const entries = await readdir(rootDirectory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const directoryPath = path.join(rootDirectory, entry.name);
+      const directoryStats = await stat(directoryPath);
+      const modifiedAgeMilliseconds =
+        Date.now() - directoryStats.mtime.getTime();
+
+      if (modifiedAgeMilliseconds < maxAgeMilliseconds) {
+        continue;
+      }
+
+      await rm(directoryPath, { recursive: true, force: true });
+      removedDirectories.push(directoryPath);
+    }
+  } catch (error) {
+    const nodeError = error as NodeJS.ErrnoException;
+
+    if (nodeError.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  return {
+    rootDirectory,
+    removedDirectories,
+  };
+}
+
+async function removeDirectoryIfPresent(directoryPath: string): Promise<boolean> {
+  try {
+    await rm(directoryPath, { recursive: true, force: false });
+    return true;
+  } catch (error) {
+    const nodeError = error as NodeJS.ErrnoException;
+
+    if (nodeError.code === 'ENOENT') {
+      return false;
+    }
+
+    throw error;
+  }
+}

tests/log-storage.test.ts

@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, stat, utimes } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import {
+  cleanupSavedLogs,
+  getSavedLogsRootDirectory,
+  removeSavedLogsForBuildRun,
+} from '../src/utils/log-storage.js';
+
+test('cleanupSavedLogs removes directories older than retention', async () => {
+  const baseDirectory = await mkdtemp(
+    path.join(tmpdir(), 'xcode-cloud-mcp-cleanup-test-'),
+  );
+  const rootDirectory = getSavedLogsRootDirectory(baseDirectory);
+  const staleDirectory = path.join(rootDirectory, 'stale-build');
+  const freshDirectory = path.join(rootDirectory, 'fresh-build');
+
+  await mkdir(staleDirectory, { recursive: true });
+  await mkdir(freshDirectory, { recursive: true });
+
+  const staleDate = new Date(Date.now() - 48 * 60 * 60 * 1000);
+  await utimes(staleDirectory, staleDate, staleDate);
+
+  const cleanupResult = await cleanupSavedLogs({
+    rootDirectory,
+    maxAgeHours: 24,
+  });
+
+  assert.equal(cleanupResult.removedDirectories.includes(staleDirectory), true);
+  await assert.rejects(stat(staleDirectory));
+  await stat(freshDirectory);
+});
+
+test('removeSavedLogsForBuildRun removes one build directory', async () => {
+  const baseDirectory = await mkdtemp(
+    path.join(tmpdir(), 'xcode-cloud-mcp-remove-test-'),
+  );
+  const rootDirectory = getSavedLogsRootDirectory(baseDirectory);
+  const buildRunId = 'build-123';
+  const buildDirectory = path.join(rootDirectory, buildRunId);
+
+  await mkdir(buildDirectory, { recursive: true });
+
+  const removalResult = await removeSavedLogsForBuildRun(buildRunId, {
+    baseDirectory,
+  });
+
+  assert.equal(removalResult.removed, true);
+  assert.equal(removalResult.removedDirectory, buildDirectory);
+  await assert.rejects(stat(buildDirectory));
+});

tests/smoke.test.ts

@@ -32,13 +32,16 @@ test('server starts over stdio and exposes the expected tools', async () => {
   const toolNames = tools.tools.map((tool) => tool.name).sort();
 
   assert.deepEqual(toolNames, [
+    'cleanup_saved_logs',
     'get_build_issues',
     'get_build_logs',
+    'get_failed_tests',
     'get_test_artifacts',
     'get_test_results',
     'list_build_runs',
     'list_products',
     'list_workflows',
+    'materialize_build_logs',
   ]);
 
   await client.close();