Add scope validation option to inventory Builder

[Copilot]

Summary

Adds WithRequireScopes(bool) option to inventory Builder that validates tools have scope definitions at build time, preventing tools from being deployed without proper OAuth scope configuration.

Why

Tools can currently be added to inventory without defining RequiredScopes or AcceptedScopes, creating risk for PAT filtering and scope challenge functionality.

What changed

• Added requireScopes field to Builder struct
• Implemented WithRequireScopes(bool) method for builder chain
• Added validation in Build() that panics if requireScopes=true and any tool has both RequiredScopes and AcceptedScopes set to nil
• Empty slices ([]string{}) explicitly allowed for tools requiring no scopes
• Created comprehensive test suite (9 tests) covering validation scenarios

MCP impact

• No tool or API changes — Internal builder API only, no MCP tools affected

Prompts tested (tool changes only)

N/A

Security / limits

• No security or limits impact — Validation is opt-in and runs at build time

Tool renaming

• I am not renaming tools as part of this PR

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Docs

• Updated (README / docs / examples) — Builder struct and method documentation updated with usage examples

Example Usage

inv := inventory.NewBuilder().
    SetTools(tools).
    WithRequireScopes(true).  // Panics if any tool lacks scope definitions
    Build()

Validation distinguishes between:

• nil scopes (validation error) — tool author forgot to define scopes
• Empty slices []string{} (allowed) — tool explicitly requires no scopes

Original prompt

Problem

Currently, tools can be added to the inventory without defining OAuth scopes (RequiredScopes and AcceptedScopes). This creates a risk of tools being deployed without proper scope definitions, which affects PAT filtering and scope challenge functionality.

Solution

Add a WithRequireScopes(bool) option to the inventory Builder that, when enabled, validates that all tools have either:

1. Non-empty RequiredScopes and AcceptedScopes defined, OR
2. Are explicitly marked as not requiring scopes (empty slices are acceptable if intentional)

The validation should happen in the Build() method and should panic if any tool is missing scopes when WithRequireScopes(true) is set.

Implementation Details

1. Add a requireScopes bool field to the Builder struct
2. Add WithRequireScopes(require bool) *Builder method
3. In Build(), if requireScopes is true, iterate through all tools and panic if any tool has both RequiredScopes and AcceptedScopes as nil (not just empty)
4. Update the Builder documentation to mention this validation option

Example Usage

inv := inventory.NewBuilder().
    SetTools(tools).
    WithRequireScopes(true).  // Panics if any tool lacks scope definitions
    Build()

Acceptance Criteria

• WithRequireScopes(true) causes Build() to panic if any tool has nil RequiredScopes AND nil AcceptedScopes
• Empty slices []string{} are allowed (explicit "no scopes needed")
• Add tests for the new validation
• Update Builder godoc to document this option

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.