# branch-protection Specification

## Purpose
TBD - created by archiving change branch-protection-management. Update Purpose after archive.
## Requirements
### Requirement: List branch protection rules (bounded)

The server SHALL provide a `list_branch_protections` tool that returns the branch protection rules of a repository given `owner` and `repo`. The tool SHALL expose caller-controlled `page` and `limit` bounds and the response SHALL be resumable by echoing the page that was returned, satisfying `docs/design/output-bounding.md`.

#### Scenario: List returns the repository's rules

- **WHEN** `list_branch_protections` is called with a valid `owner` and `repo`
- **THEN** the result SHALL contain the repository's branch protection rules as returned by `GET /repos/{owner}/{repo}/branch_protections`
- **AND** each rule SHALL include at least its `rule_name`, `branch_name`, `enable_status_check`, `status_check_contexts`, and `required_approvals`

#### Scenario: Caller bounds the page size

- **WHEN** `list_branch_protections` is called with `limit` set to N
- **THEN** the request to Forgejo SHALL carry a page size of N
- **AND** the response SHALL indicate the page returned so the caller can request the next page

### Requirement: Get a branch protection rule

The server SHALL provide a `get_branch_protection` tool that returns a single rule given `owner`, `repo`, and the rule identifier (`rule`).

#### Scenario: Existing rule is returned

- **WHEN** `get_branch_protection` is called with an `owner`, `repo`, and a `rule` that exists
- **THEN** the result SHALL contain that rule's full protection state

#### Scenario: Missing rule yields an error

- **WHEN** `get_branch_protection` is called with a `rule` that does not exist
- **THEN** the tool SHALL return an error result rather than an empty success

### Requirement: Create a branch protection rule

The server SHALL provide a `create_branch_protection` tool that creates a rule via `POST /repos/{owner}/{repo}/branch_protections`. The tool SHALL require `owner`, `repo`, and `branch_name`; `rule_name` SHALL be optional (Forgejo defaults it to `branch_name`). The tool SHALL round-trip `status_check_contexts` exactly.

#### Scenario: Create enforces status checks

- **WHEN** `create_branch_protection` is called with `enable_status_check` true and `status_check_contexts` set to a list of contexts
- **THEN** the request body sent to Forgejo SHALL contain `enable_status_check: true` and the exact `status_check_contexts` list
- **AND** the result SHALL reflect the created rule with those contexts

#### Scenario: Create requires a branch name

- **WHEN** `create_branch_protection` is called without `branch_name`
- **THEN** the tool SHALL return an error result and SHALL NOT call Forgejo

### Requirement: Edit a branch protection rule with PATCH semantics

The server SHALL provide an `edit_branch_protection` tool that updates a rule via `PATCH /repos/{owner}/{repo}/branch_protections/{rule}`. The tool SHALL only send fields the caller explicitly provides; fields the caller omits SHALL be left unchanged on the server.

#### Scenario: Editing one field leaves others untouched

- **WHEN** `edit_branch_protection` is called with only `required_approvals` set to 2
- **THEN** the request body sent to Forgejo SHALL set `required_approvals` to 2
- **AND** the other protection fields the caller did not pass SHALL be sent as `null` (leave-unchanged), never as a concrete value such as `false` that would silently relax protection

#### Scenario: Editing status checks round-trips the contexts

- **WHEN** `edit_branch_protection` is called with `status_check_contexts` set to a list
- **THEN** the request body SHALL contain that exact list

### Requirement: Delete a branch protection rule

The server SHALL provide a `delete_branch_protection` tool that removes a rule via `DELETE /repos/{owner}/{repo}/branch_protections/{rule}` and reports success.

#### Scenario: Existing rule is deleted

- **WHEN** `delete_branch_protection` is called for a rule that exists
- **THEN** Forgejo SHALL receive a delete request for that rule
- **AND** the tool SHALL return a success result confirming removal

### Requirement: Branch protections collection resource (bounded)

The server SHALL expose a resource-template `forgejo://repo/{owner}/{repo}/branch_protections` that returns the repository's protection rules as a read-only JSON document. The embedded list SHALL be bounded at `EmbeddedListCap` using the shared `resource.Bounded` helper, and when truncated SHALL carry the truncation sentinel and name `list_branch_protections` as the tool to fetch the remainder.

#### Scenario: Collection resource returns bounded rules

- **WHEN** the resource `forgejo://repo/{owner}/{repo}/branch_protections` is read for a repo with rules
- **THEN** the payload SHALL list the rules up to `EmbeddedListCap`
- **AND** when more than `EmbeddedListCap` rules exist, the payload SHALL set a truncation indicator naming `list_branch_protections`

#### Scenario: Unknown repository maps to a not-found resource error

- **WHEN** the collection resource is read for a repository that does not exist
- **THEN** the handler SHALL return a resource error mapped from the Forgejo 404 response

### Requirement: Single branch protection resource

The server SHALL expose a resource-template `forgejo://repo/{owner}/{repo}/branch_protection/{rule}` that returns one rule's protection state as a read-only JSON document.

#### Scenario: Single rule resource returns its state

- **WHEN** the resource `forgejo://repo/{owner}/{repo}/branch_protection/{rule}` is read for an existing rule
- **THEN** the payload SHALL contain that rule's protection state including `status_check_contexts` and `required_approvals`

#### Scenario: Malformed URI maps to an invalid-params error

- **WHEN** a `forgejo://repo/...` branch-protection URI is read that does not match the template
- **THEN** the handler SHALL return a resource error with the invalid-params code