Public: anyone can read this; the crew can change it.

GET a repository's commits answers `{ items, next_cursor }`, and every test that reads it is updated #5087

Parked opened this
Closed without merging

scout/forge:scout/5083-get-a-repository-s-commits-answers-items → main 9 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
12 files changed +30 −18
docs/MCP.md +1 −1
@@ -56,7 +56,7 @@ for a tunnel and a forge that sleeps.
5656 | `close` | `{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason` | yes |
5757 | `cloud_account` | `{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says` | yes |
5858 | `cloud_accounts` | the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them) | yes |
59 | `commits` | `{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer | |
59 | `commits` | `{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), answered as `{ commits }`, not the route's `{ items, next_cursor }`; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer | |
6060 | `confirm_wait` | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes |
6161 | `contribute` | for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose | |
6262 | `converge` | the fork's crew merges where both sides changed the same files; comes back as a pull | yes |
scripts/home-eval.ts +1 −1
@@ -40,7 +40,7 @@ async function truth(): Promise<Truth> {
4040 for (let i = 0; i < live.length; i += 8) {
4141 await Promise.all(
4242 live.slice(i, i + 8).map(async (full) => {
43 const log: { date: string }[] = await get(`/api/v1/repos/${full}/commits?limit=1`);
43 const log = ((await get(`/api/v1/repos/${full}/commits?limit=1`)) as { items: { date: string }[] }).items;
4444 if (log[0] !== undefined && Date.now() - Date.parse(log[0].date) > 3 * DAY) quiet.push(full);
4545 }),
4646 );
src/contract/openapi/routes/getApiV1ReposOwnerNameCommits.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: `${REPO}/commits`, summary: "List commits newest first from `ref` (default: the default branch) as a bare array of { oid, parents, author, email, date, subject, body }; limit 1 to 100 (default 30); an unsafe ref is a 422 bad_ref; a private repository needs a token", auth: false, query: { ref: "string", limit: "integer" } };
3 export const route: Route = { method: "get", path: `${REPO}/commits`, summary: "List commits newest first from `ref` (default: the default branch) answers { items: [{ oid, parents, author, email, date, subject, body }], next_cursor }; next_cursor is always null (one page), limit 1 to 100 (default 30); an unsafe ref is a 422 bad_ref; a private repository needs a token", auth: false, query: { ref: "string", limit: "integer" } };
src/http/api.ts +1 −1
@@ -2967,7 +2967,7 @@ export function apiRoutes(router: Router<Handler>): void {
29672967 const log = await timePhaseAsync(ctx.request, "git", () =>
29682968 commitLog(dirOf(ctx, repo), ref, { limit }),
29692969 );
2970 return timePhase(ctx.request, "render", () => json(log.ok ? log.value : []));
2970 return timePhase(ctx.request, "render", () => json({ items: log.ok ? log.value : [], next_cursor: null }));

The shape is right, but src/contract/openapi/routes/getApiV1ReposOwnerNameCommits.ts still publishes "a bare array" for this route. The preview's /api/v1/openapi.json shows it. Update that summary in this pull. The MCP commits doc ("as GET …/commits answers") is now wrong too.

29712971 });
29722972
29732973 router.add("GET", "/api/v1/repos/:owner/:name/commits/:oid", async (ctx) => {
src/http/mcp/tools/commits.ts +1 −1
@@ -7,7 +7,7 @@ import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"
77
88 export const tool: Tool = {
99 name: "commits",
10 doc: "`{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer",
10 doc: "`{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), answered as `{ commits }`, not the route's `{ items, next_cursor }`; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer",
1111 description:
1212 "Recent commits; `oid`: one commit, diff and check.",
1313 inputSchema: {
test/api-commit-timing.test.ts +1 −1
@@ -43,7 +43,7 @@ beforeAll(async () => {
4343 });
4444 if (!done.ok) throw new Error(JSON.stringify(done.error));
4545 const res = await fetch(`${servers.url}/api/v1/repos/alice/r/commits?ref=main`, { headers: { cookie } });
46 oid = ((await res.json()) as { oid: string }[])[0]!.oid;
46 oid = ((await res.json()) as { items: { oid: string }[] }).items[0]!.oid;
4747 });
4848
4949 afterAll(async () => {
test/api-commits-timing.test.ts +3 −3
@@ -62,14 +62,14 @@ test("the commits list names session, git, render in order", async () => {
6262 const got = await phases("/api/v1/repos/alice/r/commits");
6363 expect(got.status).toBe(200);
6464 expect(got.names).toEqual(["session", "git", "render"]);
65 expect(JSON.parse(got.body)[0].subject).toBe("change");
65 expect(JSON.parse(got.body).items[0].subject).toBe("change");
6666 });
6767
68 test("an unknown ref still names the three phases and answers []", async () => {
68 test("an unknown ref still names the three phases and answers an empty page", async () => {
6969 const got = await phases("/api/v1/repos/alice/r/commits?ref=nope");
7070 expect(got.status).toBe(200);
7171 expect(got.names).toEqual(["session", "git", "render"]);
72 expect(JSON.parse(got.body)).toEqual([]);
72 expect(JSON.parse(got.body)).toEqual({ items: [], next_cursor: null });
7373 });
7474
7575 test("a bad ref is a 422 bad_ref", async () => {
test/api-list-shape.test.ts +7 −1
@@ -14,13 +14,13 @@ import { createIssue } from "../src/core/issues.ts";
1414 import { apiRoutes } from "../src/http/api.ts";
1515 import { serve, type Servers } from "../src/http/server.ts";
1616 import { seedAdmin } from "./helpers/admin.ts";
17 import { ROUTES } from "../src/contract/openapi.ts";
1718
1819 /** Routes that answer a bare array today → the open issue that changes them. */
1920 const BARE: Record<string, string> = {
2021 "/api/v1/repos/:owner/:name/forks": "#4843",
2122 "/api/v1/repos/:owner/:name/labels": "#4843",
2223 "/api/v1/repos/:owner/:name/hooks": "#4843",
23 "/api/v1/repos/:owner/:name/commits": "#5083",
2424 "/api/v1/user/origins": "#4841",
2525 "/api/v1/user/origin-apps": "#4841",
2626 };
@@ -86,3 +86,9 @@ test("an allowlisted route that no longer answers a bare array leaves the list",
8686 }
8787 expect(stale).toEqual([]);
8888 });
89
90 test("no published summary calls a route's answer a bare array unless the allowlist names it", () => {
91 const colon = (path: string) => path.replace(/\{(\w+)\}/g, ":$1");
92 const liars = ROUTES.filter((r) => /bare array/i.test(r.summary) && !(colon(r.path) in BARE)).map((r) => `${r.method} ${r.path}`);
93 expect(liars).toEqual([]);
94 });
test/parity.test.ts +5 −1
@@ -99,7 +99,11 @@ describe("parity: full control through actions and the API", () => {
9999 return {
100100 status: res.status,
101101 json: (Array.isArray(parsed) ? {} : parsed) as Json,
102 list: (Array.isArray(parsed) ? parsed : []) as Json[],
102 list: (Array.isArray(parsed)
103 ? parsed
104 : Array.isArray((parsed as Json).items)
105 ? (parsed as Json).items
106 : []) as Json[],
103107 };
104108 }
105109
test/read-api.test.ts +5 −3
@@ -83,9 +83,11 @@ describe("read-back API (contents, branches, commits)", () => {
8383 const commits = (await (
8484 await api("/api/v1/repos/dev/lib/commits?ref=main")
8585 ).json()) as {
86 subject: string;
87 }[];
88 expect(commits[0]?.subject).toBe("init");
86 items: { subject: string }[];
87 next_cursor: string | null;
88 };
89 expect(commits.next_cursor).toBeNull();
90 expect(commits.items[0]?.subject).toBe("init");
8991 });
9092
9193 test("contents reads a file's text at a ref", async () => {
test/view-source.test.ts +2 −2
@@ -128,9 +128,9 @@ describe("RepoSource: one repository, two places to read it from", () => {
128128 { path: "src/index.ts", content: SOURCE_FILE },
129129 ],
130130 });
131 const upstreamCommits = (await (
131 const upstreamCommits = ((await (
132132 await fetch(`${originServers.url}/api/v1/repos/octo/widgets/commits`)
133 ).json()) as { oid: string; subject: string }[];
133 ).json()) as { items: { oid: string; subject: string }[] }).items;
134134
135135 // The fake Forgejo API in front of it, describing the same repository —
136136 // the same files, the same log, so "equivalent" is a claim with teeth.
test/web-browse.test.ts +2 −2
@@ -129,9 +129,9 @@ describe("browsing an origin repository on the web", () => {
129129 { path: "src/index.ts", content: SOURCE_FILE },
130130 ],
131131 });
132 const upstream = (await (
132 const upstream = ((await (
133133 await fetch(`${originServers.url}/api/v1/repos/octo/widgets/commits`)
134 ).json()) as { oid: string }[];
134 ).json()) as { items: { oid: string }[] }).items;
135135 const tip = upstream[0]!.oid;
136136
137137 const state = newFakeState("forgejo", ORIGIN_LOGIN, ORIGIN_TOKEN);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs