Add forgejo_milestone_view tool #22

New issue

Closed

opened 2026-08-18 02:34:20 +00:00 by david · 1 comment

david commented

2026-08-18 02:34:20 +00:00

Owner

Summary

Add a viewMilestone() function to src/milestones.ts and register a forgejo_milestone_view tool, so a single milestone's full details (description, due date, open/closed issue counts) can be inspected by id — mirroring forgejo_issue_view.

Background

Depends on: #20 (Add forgejo_milestone_create tool) (needs the ForgejoMilestone interface, milestonePath() helper, and src/milestones.ts scaffolding).

The existing forgejo_issue_view tool (viewIssue() in src/issues.ts) is the reference pattern: a single GET by id/number, returning the full resource with no filters. forgejo_milestone_view follows the same shape for milestones.

Implementation Details

Confirmed Forgejo/Gitea API v1 contract:

GET /repos/{owner}/{repo}/milestones/{id} (operationId issueGetMilestone)

Path param id — per Forgejo's own behavior this is resolved by numeric ID, with a fallback to milestone name if the id doesn't match numerically. Document the tool's id param as "Milestone id (from forgejo_list_milestones)" — primary usage is by id.

Response (200): ForgejoMilestone. Errors: 404 if not found.

Files to change:

src/milestones.ts:
- Add viewMilestone(target: ForgejoTarget, id: number): Promise<Result<ForgejoMilestone, ApiError>> — GET /repos/{owner}/{repo}/milestones/{id} via forgejoApiCall, using the milestonePath(target, id) helper.
src/index.ts:
- Import viewMilestone from ./milestones.
- Register forgejo_milestone_view tool:
  - label: "View Milestone"
  - promptSnippet: "View a Forgejo milestone"
  - promptGuidelines: e.g. ["Use forgejo_milestone_view to check open/closed issue counts before editing or closing a milestone."]
  - parameters: Type.Object({ ...targetOverrides, id: Type.Integer({ minimum: 1, description: "Milestone id" }) })
  - execute: resolve target, call viewMilestone, return via formatMilestone(result.value, "Milestone") (the helper added in the create-milestone issue).
tests/milestones.test.ts: add unit tests for viewMilestone() — verify URL construction (/repos/{owner}/{repo}/milestones/{id}), GET method, success and 404-error propagation.
Tool-registration tests: add coverage for forgejo_milestone_view — schema shape, execute() success/error paths.

Acceptance Criteria

viewMilestone() exists in src/milestones.ts, calls GET /repos/{owner}/{repo}/milestones/{id}, and returns Result<ForgejoMilestone, ApiError>.
forgejo_milestone_view tool is registered with a required id param plus targetOverrides.
Output includes title, state, description, due_on, and open/closed issue counts in both text and details.
A 404 (milestone not found) surfaces the existing NOT_FOUND error message unchanged.
Unit tests cover viewMilestone() and the tool registration/execution path.
npm test and npm run check pass with no regressions.

Test Plan

Run npm test — new tests for viewMilestone() and forgejo_milestone_view pass; full suite green.
Run npm run check — lint/typecheck passes.
Manual smoke test: create a milestone, note its id, call forgejo_milestone_view id=<id> and confirm the returned fields match what's shown in the Forgejo web UI. Call with a nonexistent id and confirm a clear 404 error message.

## Summary Add a `viewMilestone()` function to `src/milestones.ts` and register a `forgejo_milestone_view` tool, so a single milestone's full details (description, due date, open/closed issue counts) can be inspected by id — mirroring `forgejo_issue_view`. ## Background **Depends on:** #20 (Add forgejo_milestone_create tool) (needs the `ForgejoMilestone` interface, `milestonePath()` helper, and `src/milestones.ts` scaffolding). The existing `forgejo_issue_view` tool (`viewIssue()` in `src/issues.ts`) is the reference pattern: a single GET by id/number, returning the full resource with no filters. `forgejo_milestone_view` follows the same shape for milestones. ## Implementation Details **Confirmed Forgejo/Gitea API v1 contract:** `GET /repos/{owner}/{repo}/milestones/{id}` (operationId `issueGetMilestone`) Path param `id` — per Forgejo's own behavior this is resolved by numeric ID, with a fallback to milestone name if the id doesn't match numerically. Document the tool's `id` param as "Milestone id (from forgejo_list_milestones)" — primary usage is by id. Response (`200`): `ForgejoMilestone`. Errors: `404` if not found. **Files to change:** 1. `src/milestones.ts`: - Add `viewMilestone(target: ForgejoTarget, id: number): Promise<Result<ForgejoMilestone, ApiError>>` — GET `/repos/{owner}/{repo}/milestones/{id}` via `forgejoApiCall`, using the `milestonePath(target, id)` helper. 2. `src/index.ts`: - Import `viewMilestone` from `./milestones`. - Register `forgejo_milestone_view` tool: - `label`: "View Milestone" - `promptSnippet`: "View a Forgejo milestone" - `promptGuidelines`: e.g. `["Use forgejo_milestone_view to check open/closed issue counts before editing or closing a milestone."]` - `parameters`: `Type.Object({ ...targetOverrides, id: Type.Integer({ minimum: 1, description: "Milestone id" }) })` - `execute`: resolve target, call `viewMilestone`, return via `formatMilestone(result.value, "Milestone")` (the helper added in the create-milestone issue). 3. `tests/milestones.test.ts`: add unit tests for `viewMilestone()` — verify URL construction (`/repos/{owner}/{repo}/milestones/{id}`), GET method, success and 404-error propagation. 4. Tool-registration tests: add coverage for `forgejo_milestone_view` — schema shape, execute() success/error paths. ## Acceptance Criteria - [ ] `viewMilestone()` exists in `src/milestones.ts`, calls `GET /repos/{owner}/{repo}/milestones/{id}`, and returns `Result<ForgejoMilestone, ApiError>`. - [ ] `forgejo_milestone_view` tool is registered with a required `id` param plus `targetOverrides`. - [ ] Output includes title, state, description, due_on, and open/closed issue counts in both text and `details`. - [ ] A 404 (milestone not found) surfaces the existing `NOT_FOUND` error message unchanged. - [ ] Unit tests cover `viewMilestone()` and the tool registration/execution path. - [ ] `npm test` and `npm run check` pass with no regressions. ## Test Plan 1. Run `npm test` — new tests for `viewMilestone()` and `forgejo_milestone_view` pass; full suite green. 2. Run `npm run check` — lint/typecheck passes. 3. Manual smoke test: create a milestone, note its id, call `forgejo_milestone_view id=<id>` and confirm the returned fields match what's shown in the Forgejo web UI. Call with a nonexistent id and confirm a clear 404 error message.

david added the

enhancement

label

2026-08-18 02:34:20 +00:00

david referenced this issue

2026-08-18 02:34:38 +00:00

Extend forgejo extension: milestone create/list + label create tools #13

david referenced this issue

2026-08-18 02:35:15 +00:00

Update README.md and DESIGN.md for milestone CRUD + label create #27

david referenced this issue

2026-08-18 02:35:16 +00:00