feat: add include_sha parameter to get_file_contents tool

[yonaka15]

Summary

This PR addresses issue #595 by adding an optional include_sha parameter to the get_file_contents tool, providing a more flexible and performant solution than the previous approach in PR #599.

Problem

The get_file_contents tool was missing the SHA hash in its response, which is essential for subsequent file update operations using create_or_update_file. The SHA is required by the GitHub API for any update operation.

Solution

Instead of always returning metadata (as in PR #599), this PR adds an include_sha boolean parameter that allows users to explicitly choose between:

• Raw content (default): Fast retrieval via GitHub's Raw API
• File metadata: Complete file information including SHA, size, type via Contents API

Key Features

• ✅ Backward compatible: Default behavior unchanged
• ✅ Performance optimized: Raw API used when metadata not needed
• ✅ Flexible: Works for both files and directories
• ✅ Comprehensive: Returns complete GitHub API metadata when requested
• ✅ Well-tested: Full test coverage for all scenarios

Usage Examples

// Get file content (existing behavior)
get_file_contents({ owner: "user", repo: "repo", path: "file.md" })
// Returns: raw file content

// Get file metadata including SHA
get_file_contents({ 
  owner: "user", 
  repo: "repo", 
  path: "file.md", 
  include_sha: true 
})
// Returns: { name, path, sha, size, type, content, encoding, ... }

Changes Made

• Added include_sha boolean parameter to tool schema
• Updated implementation to conditionally use Contents API vs Raw API
• Enhanced tool description to document new parameter
• Added comprehensive test coverage for all scenarios
• Updated tool snapshots to reflect schema changes

Testing

• ✅ All existing tests pass
• ✅ New test cases cover include_sha functionality
• ✅ Edge cases and error scenarios tested
• ✅ Both file and directory metadata retrieval verified

Supersedes

This PR supersedes #599 by providing a more user-friendly and performant solution to the same problem.

Closes #595
Supersedes #599

[Copilot]

Pull Request Overview

This PR adds an optional include_sha parameter to the get_file_contents tool, allowing users to choose between fast raw content retrieval and detailed file metadata (including SHA) needed for file update operations.

• Introduce the include_sha boolean parameter to the tool schema and update its description.
• Modify the API call logic to conditionally use either the raw content or the GitHub Contents API based on the include_sha value.
• Update tests and snapshots to cover the new include_sha functionality.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
pkg/github/repositories_test.go	Added schema check for include_sha and new test cases for both metadata and raw content fetching.
pkg/github/repositories.go	Extended tool description, added the include_sha parameter, and updated API call flow and error handling accordingly.
pkg/github/toolsnaps/get_file_contents.snap	Updated snapshot description and schema to include the new include_sha parameter.

Comments suppressed due to low confidence (1)

pkg/github/repositories.go:529

• [nitpick] Consider adding an inline comment explaining why the raw content API call is skipped when include_sha is true, to improve future maintainability and clarity.

			if !includeSha && path != "" && !strings.HasSuffix(path, "/") {

[LuluBeatson]

Hi @yonaka15, thank you for your PR, returning the SHA will be useful! :)

We recommend the following changes:

• Not adding a new argument include_sha, but always returning a file's SHA
• For files, always return a resource. The SHA can be included with the text output of the tool result but the file should be a resource. This is done on repositories.go#L566-L578

So overall, the flow for files can look like:

1. First, get the SHA if not provided as a tool input. For this you can use a cheaper method, like we do for PRs (repositories.go#L516) instead of the file API.
2. Then, download the file using rawClient.GetRawContent, providing the SHA (to avoid a race condition). This is already done on repositories.go#L531
3. Return a NewToolResultResource with the file as a resource and a json message containing the SHA. i.e. You can update the "successfully downloaded text file" / "successfully downloaded binary file" text part of the tool result but keep the TextResourceContents / BlobResourceContents in repositories.go#L566-L578

Example: Tool call result with both text and resource output

Example: Tool call result with file content encoded as text (avoid this)

Thank you, we look forward to your response!