feat: add GitHub issue retrieval and updating to dev-tools CLI and MCP

[google-labs-jules]

This PR introduces new structured commands and MCP tools for managing GitHub issues.

Key changes:

• Extended tdw_services GitHubClient and Orchestrator with issue retrieval and body update capabilities.
• Added gh issue-view, gh issue-update, and gh issue-comment subcommands to td_cli.py.
• Exposed github.issue_view, github.issue_update, and github.issue_comment tools in the boomtick-mcp server.
• Updated cli-schema.json to register the new commands for AI agents.
• Ensured consistent JSON output flattening and documentation in both Python and TypeScript components.

Fixes #2661

---

PR created automatically by Jules for task 3697387033533382433 started by @arii

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[github-actions]

🚀 Deployment Details (Last updated: Jun 26, 2026, 3:16 PM PST)

🚀 Pushed to gh-pages; publish in progress

• Preview URL: https://arii.github.io/tech-dancer/feat/gh-issue-tools-3697387033533382433/
• Preview Dashboard: https://arii.github.io/tech-dancer/previews/index.html
• Commit SHA: dd83b42
• Marker File: verify here

[github-actions]

👁️ Gemini Code Review Agent

Powered by Gemini 3.x

Reviewing: PR #2991

Code Review Feedback

[ARCHITECTURE] Review

Error: failed to execute ARCHITECTURE review. Details: [GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent: [429 Too Many Requests] Your project has exceeded its monthly spending cap. Please go to AI Studio at https://ai.studio/spend to manage your project spend cap. Learn more at https://ai.google.dev/gemini-api/docs/billing#project-spend-caps.

[PERFORMANCE] Review

Error: failed to execute PERFORMANCE review. Details: [GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent: [429 Too Many Requests] Your project has exceeded its monthly spending cap. Please go to AI Studio at https://ai.studio/spend to manage your project spend cap. Learn more at https://ai.google.dev/gemini-api/docs/billing#project-spend-caps.

[SECURITY] Review

Error: failed to execute SECURITY review. Details: [GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent: [429 Too Many Requests] Your project has exceeded its monthly spending cap. Please go to AI Studio at https://ai.studio/spend to manage your project spend cap. Learn more at https://ai.google.dev/gemini-api/docs/billing#project-spend-caps.

[STYLE] Review

Error: failed to execute STYLE review. Details: [GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent: [429 Too Many Requests] Your project has exceeded its monthly spending cap. Please go to AI Studio at https://ai.studio/spend to manage your project spend cap. Learn more at https://ai.google.dev/gemini-api/docs/billing#project-spend-caps.

---

Generated by gemini-code-review

[github-actions]

🐙 GitHub Models Code Review

Powered by GitHub Models

Reviewing: PR #2991

Model: gpt-4o

Code Review Feedback

[ARCHITECTURE] Review

Error: failed to execute ARCHITECTURE review. Details: GitHub Models API error: 429 Too Many Requests - {"error":{"code":"RateLimitReached","message":"Rate limit of 2 per 0s exceeded for UserConcurrentRequests. Please wait 0 seconds before retrying.","details":"Rate limit of 2 per 0s exceeded for UserConcurrentRequests. Please wait 0 seconds before retrying."}}

[PERFORMANCE] Review

Review Summary

This PR introduces new GitHub issue management commands (issue-view, issue-update, issue-comment) to the BoomtickMCPServer and CLI tools. The implementation appears functional and adheres to the existing patterns in the codebase. However, there are several HIGH severity issues related to error handling, resource management, and performance that need to be addressed before merging.

---

Findings

High Severity Issues

1. Improper Error Handling in issueCommentHandler

   • File: boomtick-mcp/src/tools/github.issue_comment.ts
   • Line: 25
   • Snippet: throw new Error(\Failed to post comment: ${result.stderr}`);`
   • Issue: The error message directly includes result.stderr, which could contain sensitive or irrelevant information. This is a potential security and debugging issue.
   • Fix Summary: Sanitize stderr before including it in the error message. For example, only include relevant parts or log the full details separately.

2. Improper Error Handling in issueUpdateHandler

   • File: boomtick-mcp/src/tools/github.issue_update.ts
   • Line: 20
   • Snippet: throw new Error(\Failed to update issue: ${result.stderr}`);`
   • Issue: Same as above—stderr is directly exposed in the error message.
   • Fix Summary: Sanitize stderr before including it in the error message.

3. Improper Error Handling in issueViewHandler

   • File: boomtick-mcp/src/tools/github.issue_view.ts
   • Line: 13
   • Snippet: throw new Error(\Failed to view issue: ${result.stderr}`);`
   • Issue: Same as above—stderr is directly exposed in the error message.
   • Fix Summary: Sanitize stderr before including it in the error message.

4. Temporary File Cleanup in issueCommentHandler

   • File: boomtick-mcp/src/tools/github.issue_comment.ts
   • Line: 34
   • Snippet: await fs.unlink(tmpFile).catch(() => {});
   • Issue: The catch block silently suppresses errors during file cleanup. If the file cannot be deleted, it could lead to resource leaks or security risks.
   • Fix Summary: Log the error or handle it explicitly to ensure proper cleanup.

5. Temporary File Cleanup in issueUpdateHandler

   • File: boomtick-mcp/src/tools/github.issue_update.ts
   • Line: 33
   • Snippet: await fs.unlink(tmpFile).catch(() => {});
   • Issue: Same as above—silent suppression of errors during file cleanup.
   • Fix Summary: Log the error or handle it explicitly to ensure proper cleanup.

6. Performance Concern: Redundant File Writes

   • File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts
   • Line: 12, 12
   • Snippet: await fs.writeFile(tmpFile, params.body);
   • Issue: Writing temporary files for CLI commands introduces unnecessary I/O overhead. This could be optimized by using in-memory streams or piping the content directly to the CLI.
   • Fix Summary: Investigate whether the CLI supports direct input via stdin or other mechanisms to avoid file I/O.

---

Medium Severity Issues

1. Missing Validation for body Content
   • File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts
   • Line: 8, 8
   • Snippet: body: z.string().describe("The content of the comment.")
   • Issue: The body field is validated as a string but lacks checks for length or content (e.g., empty strings). This could lead to invalid or empty comments being posted.
   • Fix Summary: Add validation for minimum length and/or non-empty content.

---

Low Severity Issues (Nitpicks)

1. Redundant Error Handling in CLI Commands

   • File: dev-tools/tdw_services/cli.py
   • Line: 65, 79, 93
   • Snippet: except Exception as e: err(ctx, str(e))
   • Issue: Catching generic Exception without specific handling can mask underlying issues.
   • Fix Summary: Replace except Exception with specific error types or log the exception details for debugging.

2. Potential for Race Conditions in Temporary File Handling

   • File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts
   • Line: 12, 12
   • Snippet: const tmpFile = path.join(os.tmpdir(), \issue-comment-${params.issueNumber}-${Date.now()}.md`);`
   • Issue: Using Date.now() for temporary file names could lead to collisions in high-concurrency scenarios.
   • Fix Summary: Use a more robust mechanism for generating unique file names, such as crypto.randomUUID().

---

Final Verdict

Given the presence of multiple HIGH severity issues related to error handling, resource management, and performance, this PR cannot be approved in its current state. The identified issues must be addressed to ensure robustness, security, and efficiency.

---

Findings JSON

[SECURITY] Review

Review Summary

The diff introduces new GitHub issue management commands (issue-view, issue-update, issue-comment) to the BoomtickMCPServer and CLI tools. These commands allow viewing, updating, and commenting on GitHub issues via structured inputs. While the implementation is generally sound, there are several high-severity security and robustness issues that need to be addressed before merging.

---

High Severity Issues (Blocking)

1. Unvalidated Input for File Paths in issue_update and issue_comment

• File: boomtick-mcp/src/tools/github.issue_update.ts and boomtick-mcp/src/tools/github.issue_comment.ts
• Lines:

  const tmpFile = path.join(os.tmpdir(), `issue-update-${params.issueNumber}-${Date.now()}.md`);
  const tmpFile = path.join(os.tmpdir(), `issue-comment-${params.issueNumber}-${Date.now()}.md`);

• Issue: The temporary file paths are constructed using user-controlled input (params.issueNumber). This introduces a potential path traversal vulnerability if params.issueNumber is maliciously crafted to include ../ or other path manipulation techniques.
• Fix Summary: Use a secure method to generate temporary file names, such as fs.mkdtemp or a library like tmp. Avoid directly embedding user input in file paths.

---

2. Lack of Output Validation for runCommand Results

• File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts, boomtick-mcp/src/tools/github.issue_view.ts
• Lines:

  const output = JSON.parse(result.stdout);
  if (output.status === "error") {
    throw new Error(`Failed to post comment: ${output.message}`);
  }

• Issue: The result.stdout is parsed as JSON without validation. If the td-cli command is compromised or outputs unexpected data, this could lead to runtime errors or injection vulnerabilities.
• Fix Summary: Use a schema validation library (e.g., zod) to validate the structure of result.stdout before accessing its properties.

---

3. Potential Command Injection in runCommand

• File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts, boomtick-mcp/src/tools/github.issue_view.ts
• Lines:

  const result = await runCommand("td-cli", ["gh", "issue-comment", params.issueNumber.toString(), "--file", tmpFile]);
  const result = await runCommand("td-cli", ["gh", "issue-update", params.issueNumber.toString(), "--file", tmpFile]);
  const result = await runCommand("td-cli", ["gh", "issue-view", params.issueNumber.toString()]);

• Issue: The runCommand function executes shell commands, and while the arguments are passed as an array (which mitigates some risks), the params.issueNumber and tmpFile values are derived from user input. If runCommand does not properly escape or validate these inputs, it could lead to command injection.
• Fix Summary: Ensure runCommand properly escapes all arguments. Alternatively, use a library like child_process.spawn with strict argument handling.

---

4. Improper Error Handling in issueCommentHandler and issueUpdateHandler

• File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts
• Lines:

  await fs.unlink(tmpFile).catch(() => {});

• Issue: The catch block for fs.unlink silently swallows errors. If the file deletion fails (e.g., due to permission issues), the temporary file could persist, leading to potential security risks (e.g., sensitive data leakage).
• Fix Summary: Log the error or rethrow it to ensure visibility into file deletion failures.

---

5. Missing Rate-Limiting for GitHub API Calls

• File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts, boomtick-mcp/src/tools/github.issue_view.ts
• Issue: The implementation does not account for GitHub API rate limits. Repeated calls to these commands could result in API throttling or account suspension.
• Fix Summary: Implement rate-limiting and retry logic for GitHub API calls. Use libraries like p-limit or bottleneck to manage concurrency and retries.

---

Medium Severity Issues (Non-blocking)

6. Lack of Sanitization for params.body

• File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts
• Lines:

  await fs.writeFile(tmpFile, params.body);

• Issue: The params.body content is written directly to a file without sanitization. If the content contains malicious payloads (e.g., scripts), it could lead to security issues if the file is executed or processed by other tools.
• Fix Summary: Sanitize params.body to ensure it does not contain harmful content. Use libraries like DOMPurify for HTML sanitization if applicable.

7. Inconsistent Error Messages

• File: boomtick-mcp/src/tools/github.issue_comment.ts, boomtick-mcp/src/tools/github.issue_update.ts, boomtick-mcp/src/tools/github.issue_view.ts
• Issue: Error messages are inconsistent in format and detail. For example:

  throw new Error(`Failed to post comment: ${result.stderr}`);
  throw new Error(`Failed to update issue: ${output.message}`);

  Some errors include result.stderr, while others include output.message. This inconsistency can make debugging harder.
• Fix Summary: Standardize error messages to include both stderr and output.message where applicable.

---

Questions

1. Error Handling in CLI Commands

   • The CLI commands (issue_view, issue_update, issue_comment) use generic Exception handling. Should these be more specific to differentiate between expected errors (e.g., CLIError) and unexpected ones?

2. Testing for Edge Cases

   • Are there tests in place to validate edge cases, such as invalid issueNumber values, empty body content, or malformed JSON responses from td-cli?

---

Nitpicks

1. Redundant Comments

   • File: boomtick-mcp/src/tools/github.issue_comment.ts
   • Line:

     // Create a temporary file for the body as the CLI expects a file path

   • Issue: The comment is redundant as the code is self-explanatory.
   • Fix Summary: Remove unnecessary comments to improve code readability.

2. Error Message Grammar

   • File: boomtick-mcp/src/tools/github.issue_view.ts
   • Line:

     throw new Error(`Failed to view issue: ${result.stderr}`);

   • Issue: The phrase "Failed to view issue" could be rephrased for clarity.
   • Fix Summary: Consider rephrasing to "Error viewing issue: {error_message}".

---

Final Verdict

The PR introduces new functionality but contains several high-severity security issues, including potential path traversal, lack of output validation, and improper error handling. These issues must be addressed before the PR can be approved.

---

[STYLE] Review

Error: failed to execute STYLE review. Details: GitHub Models API error: 429 Too Many Requests - {"error":{"code":"RateLimitReached","message":"Rate limit of 2 per 0s exceeded for UserConcurrentRequests. Please wait 0 seconds before retrying.","details":"Rate limit of 2 per 0s exceeded for UserConcurrentRequests. Please wait 0 seconds before retrying."}}

---

Generated by github-models-code-review

[arii]

🤖 AI Technical Audit

ANTI-AI-SLOP

This PR introduces new functionality for managing GitHub issues via td-cli and boomtick-mcp tools. The overall structure follows established patterns within the codebase, specifically the CLI-Orchestrator-Service architecture in Python and the handler-schema pattern in TypeScript for MCP. This consistency is a positive.

However, I've identified one instance of inconsistency and one of code duplication (slop):

1. Inconsistent Parameter Naming in Orchestrator: The post_comment method in tdw_services/orchestrator.py was updated in its docstring to support both PRs and Issues, but its parameter name pr_number was not updated to reflect this broader scope. This creates a misleading API signature.
2. Duplicated Generic Exception Handling: In dev-tools/tdw_services/cli.py, the except Exception as e: blocks are duplicated across the new commands (issue_view, issue_update, issue_comment, and an existing one for create_issue). While log_error is called, the pattern of logging and then emitting a generic error message could be consolidated into a single helper function for better maintainability and DRY principles. This is a minor instance of slop, but an opportunity for improvement.

The additions totaled 167 lines. To address the audit ratio directive, consolidating the generic exception handling in tdw_services/cli.py by introducing a helper function would remove approximately 10-15 lines of repetitive try-except boilerplate, replacing it with cleaner, single-line calls to the helper.

FINAL RECOMMENDATION (Approved | Approved with Minor Changes | Not Approved)

Approved with Minor Changes

DEFINITION OF DONE (If recommendation is "Approved with Minor Changes", list concrete, non-ambiguous tasks required for approval).

1. Refactor Orchestrator.post_comment parameter name: Rename the pr_number parameter in tdw_services/orchestrator.py's post_comment method to entity_number (or target_number) to accurately reflect its ability to comment on both PRs and Issues. Update the docstring and all call sites in tdw_services/cli.py and potentially boomtick-mcp to use the new parameter name.
   • Verify tests. Run audit for anti-patterns. Update snapshots if necessary.
2. Centralize Generic CLI Exception Handling: Create a dedicated helper function (e.g., _handle_cli_exception) within tdw_services/cli.py or tdw_services/utils.py to encapsulate the generic except Exception as e: block. Refactor the issue_view, issue_update, and issue_comment commands (and create_issue for consistency) to use this new helper function.
   • Verify tests. Run audit for anti-patterns. Update snapshots if necessary.

Review automatically published via RepoAuditor.

[arii]

PR Review

Summary: This PR enhances the td_cli.py GitHub integration by adding subcommands for getting, updating, and commenting on issues. It updates the orchestrator to decouple file reading from API requests and expands the Python MCP server with corresponding tools (gh_get_issue, gh_update_issue, gh_issue_comment).

Findings:

• Code Organization: The change refactoring _read_safe_file out of create_issue and post_comment in orchestrator.py is a solid improvement. It correctly pushes IO handling to the CLI layer (td_cli.py) or MCP handler, ensuring the core services operate on raw strings.
• MCP Validation: In boomtick-mcp/src/github_tools.py, the added JSON schemas correctly define the inputs, and the execute_github_tool function efficiently routes these new tools.
• Documentation: dev-tools/cli-schema.json is accurately updated to include the get-issue, update-issue, and issue-comment commands, maintaining the canonical source of truth for the CLI.
• Testing: The Python unit tests in test_td_cli.py have been correctly updated to mock _read_safe_file rather than the broader functions, tightening the test suite. All CI checks pass successfully.

Recommendation: Approved. The implementation successfully expands the utility of the dev-tools to manage GitHub issues natively and over MCP, adhering to the project's abstraction boundaries.

[arii]

🤖 AI Technical Audit

ANTI-AI-SLOP

• The refactor to decouple file reading from create_issue and post_comment is a good architectural improvement. However, I noticed some redundant logic in the CLI argument handling across create_issue, issue_update, and issue_comment.
• The _handle_unexpected_error helper is a welcome addition to DRY up error handling, but keep an eye on how these exceptions are bubbled up.
• The test suite has been updated to focus on _read_safe_file instead of masking it behind CLI commands, which is cleaner.
• Minor observation: Ensure that when adding future tools, the cli-schema.json and TypeScript definitions stay in lock-step to avoid drifting interfaces.

FINAL RECOMMENDATION

Approved with Minor Changes

DEFINITION OF DONE

• Verify tests pass in the CI environment.
• Run audit for anti-patterns to ensure no new violations were introduced in tdw_services.
• Update snapshots if necessary for the CLI tool outputs.

Review automatically published via RepoAuditor.

[arii]

ANTI-AI-SLOP

The change refactoring _read_safe_file out of create_issue and post_comment in orchestrator.py is a solid improvement. MCP Validation in boomtick-mcp/src/github_tools.py correctly defines the inputs.

FINDINGS

This PR enhances the td_cli.py GitHub integration by adding subcommands for getting, updating, and commenting on issues. It updates the orchestrator to decouple file reading from API requests and expands the Python MCP server. The implementation successfully expands the utility of the dev-tools to manage GitHub issues.

FINAL RECOMMENDATION

Approved

[arii]

ANTI-AI-SLOP

The change refactoring _read_safe_file out of create_issue and post_comment in orchestrator.py is a solid improvement. MCP Validation in boomtick-mcp/src/github_tools.py correctly defines the inputs.

FINDINGS

This PR enhances the td_cli.py GitHub integration by adding subcommands for getting, updating, and commenting on issues. It updates the orchestrator to decouple file reading from API requests and expands the Python MCP server. The implementation successfully expands the utility of the dev-tools to manage GitHub issues.

FINAL RECOMMENDATION

Approved

[arii]

ANTI-AI-SLOP

The change refactoring _read_safe_file out of create_issue and post_comment in orchestrator.py is a solid improvement. MCP Validation in boomtick-mcp/src/github_tools.py correctly defines the inputs.

FINDINGS

This PR enhances the td_cli.py GitHub integration by adding subcommands for getting, updating, and commenting on issues. It updates the orchestrator to decouple file reading from API requests and expands the Python MCP server. The implementation successfully expands the utility of the dev-tools to manage GitHub issues.

FINAL RECOMMENDATION

Approved

[arii]

🤖 AI Technical Audit

ANTI-AI-SLOP

This PR introduces substantial new functionality for managing GitHub issues via the td-cli and boomtick-mcp. The overall structure is sound, following established patterns for extending both the Python CLI and the TypeScript MCP tools.

Strengths:

• The introduction of _handle_unexpected_error and _get_body_content in tdw_services/cli.py is an excellent abstraction, significantly reducing code duplication and improving consistency for commands requiring body content from either a file or literal text. This proactively addresses potential slop.
• The refactoring of td_cli.py tests to directly pass body content, rather than mock file system interactions, makes them more focused and less brittle. Retargeting _read_safe_file tests is also a good improvement.
• The cli-schema.json updates are comprehensive and correctly reflect the new commands and their input options, crucial for AI agent compatibility.
• The boomtick-mcp side adheres to existing patterns, importing new handlers and schemas, and registering the tools consistently.
• sanitizeError in TypeScript handlers is a good, concise pattern to prevent verbose error messages from leaking implementation details, though its duplication can be improved.

Areas for Improvement / Minor Slop:

• Duplicate sanitizeError: The sanitizeError function is duplicated across github.issue_view.ts, github.issue_update.ts, and github.issue_comment.ts. This is a small duplicate pattern that can be centralized.
• Inconsistent gh post-comment: The gh post-comment CLI command in tdw_services/cli.py still exclusively uses --file and calls orch._read_safe_file, despite the Orchestrator.post_comment method now directly accepting body: str and the general move towards --file | --body options for other commands. This creates an inconsistency in the CLI interface for body content input.

Overall, the new code is well-structured and follows existing patterns. The additions are substantial but justified by the new features.

FINAL RECOMMENDATION

Approved with Minor Changes

DEFINITION OF DONE

1. Refactor gh post-comment to support --body: Update the td_cli.py:gh post-comment command to accept both --file and --body arguments, utilizing the _get_body_content helper function for consistency with other commands. Verify tests. Run audit for anti-patterns. Update snapshots if necessary.
2. Update cli-schema.json for gh post-comment: Add the --body optional flag to the gh post-comment entry in cli-schema.json. Verify tests. Run audit for anti-patterns. Update snapshots if necessary.
3. Centralize sanitizeError utility: Extract the sanitizeError function from boomtick-mcp/src/tools/github.*.ts into a new shared utility file (e.g., boomtick-mcp/src/lib/error_utils.ts) and import it into the three GitHub issue handlers. Verify tests. Run audit for anti-patterns. Update snapshots if necessary.

Review automatically published via RepoAuditor.