Repository Inspector

This is a small TypeScript developer tool that inspects changes in a Git repository, runs optional validation commands, and produces a Markdown report. It can be used from a command line or exposed to AI clients through MCP.

Your task

Investigate the repository and improve it as you judge best. The starter works for a narrow happy path, but production use may expose correctness, safety, reliability, contract, output, documentation, or testing weaknesses.

You are not expected to finish everything. We care about how you investigate, prioritize, implement, verify, and explain a meaningful scope.

Product decision

This tool may be used directly by developers and by AI coding agents. Decide whether its production interface should be CLI-first, MCP-first, or hybrid. Implement improvements consistent with your decision.

There is no preferred label. Explain:

• The primary user and execution environment you assumed.
• The trust boundary and allowed capabilities.
• Reliability, discoverability, latency/context, and output-size tradeoffs.
• How the interfaces you continue to advertise stay behaviorally consistent.
• What evidence would change your decision.

Time and rules

• Maximum 90 focused minutes within 48 hours of receiving the invitation.
• Use AI coding tools freely. Verify their work and document at least one suggestion you corrected or rejected.
• Work in your own repository created from this template.
• Commit as you work and complete SUBMISSION.md in your final commit.
• Completion is not required. Accurate scope and verification matter more than a large diff.

Setup

npm install
npm run typecheck
npm test

CLI

npm run inspector -- review --repo ./path/to/repo --format markdown
npm run inspector -- review --repo ./path/to/repo --validate "npm test"

The report is written to review-report.md.

MCP

Start the stdio server with:

npm run mcp-server

It exposes a review_repository tool taking repo_path (required), base_ref (optional), and validation_commands (optional array of shell commands).

MCP arguments can be steered by content inside the repository under review (prompt injection), so running validation commands over MCP is disabled by default. To enable it, the server operator must set both of these environment variables — setting only one leaves validation disabled:

• INSPECTOR_ALLOW_VALIDATION=1
• INSPECTOR_VALIDATION_ALLOWLIST="npm test,npm run typecheck" — a comma-separated list of the exact commands permitted to run; anything else is skipped.

When validation is disabled or a command isn't on the allowlist, the tool still returns a full read-only report; the skipped command is reported with status: skipped and a reason instead of being silently dropped.

Project layout

src/core.ts         shared review orchestration
src/cli.ts          command-line adapter
src/mcp-server.ts   MCP adapter
src/git.ts          Git inspection
src/validation.ts   validation execution
src/report.ts       Markdown report generation
test/               public starter tests

When finished, submit via Security → Report a vulnerability on this repo — see SECURITY.md for exactly what to include. Do not reply by email; that submission channel is not monitored.