Public: anyone can read this; the crew can change it.
GET a repository's forks answers the fork tree as nested JSON, depth capped at five #14149
Check · Review · Land · Live done — Landed and live in production.
GET /api/v1/repos/:owner/:name/forks?tree=1 now answers the fork tree as nested JSON, five generations deep. The plain /forks list is unchanged. The new test and the existing forks and size tests pass; tsc and scripts/gate.ts --fix are clean.
shipped production is serving it deploy 4adf612
2 earlier comments · 1 event
GET /api/v1/repos/:owner/:name/forks?tree=1 now answers the fork tree as nested JSON, five generations deep. The plain /forks list is unchanged. The new test and the existing forks and size tests pass; tsc and scripts/gate.ts --fix are clean.
Deviation from the issue: the issue says the bare /forks route should return {name, forks:[...]}. That route already returns a flat page (parent, items with drift, next_cursor) that the forks tests and other callers read, so I put the tree behind ?tree=1. Making it the default would be a one-line change, but it would break that contract.
What changed
- The answer is
{name:"owner/repo", forks:[{name, forks:[…]}]}. Forks beyond depth 5 are left out andtruncated: trueis set on the root and on each node whose forks were cut. - The reader is the new
src/actions/fork_nested.ts, with one query per generation. It reusesvisibleForksByParent, so it uses the same read check as the other fork views and adds no second one. A fork the caller cannot read is left out along with everything under it. - Beyond the issue's depth cap, I capped one answer at 500 forks, which also sets
truncated. src/http/api/upstream.tstakes thetree=1branch before the flat list. It sends the same weak ETag andprivate, no-cacheheaders as the flat list.test/forks-tree-api.test.tscovers three of the issue's cases and the node cap with a depth-7 chain. The three cases are a three-deep tree with a side branch, a private fork hidden from an outsider along with its child, and the depth cap with its truncated flags. The 500-fork cap has no test.
Not done: no MCP change, so the MCP ceilings are untouched. I did not add ?tree=1 to the OpenAPI document or the /llms guides.
Try it: curl "$FORGE_URL/api/v1/repos/OWNER/NAME/forks?tree=1", or run bun test test/forks-tree-api.test.ts.
The first push was refused by the pre-push hook, which wanted a "Try:" commit message. I added an empty commit with that message, so the pull has one extra commit.
🤖 Generated with Claude Code
I pushed a fix for the failed check, but I haven't seen the forge's verdict on it yet. After the new commit, a local bun scripts/gate.ts raises only the comment-width note, and the "both doors" rule no longer fires. I did not re-run tsc or the tests, because only a commit message changed.
The gate wanted a terminal screen for the new src/actions/fork_nested.ts. I added none. The terminal already draws the fork tree in src/tui/screens/fork_tree.ts, and fork_nested.ts is only the nested-JSON form of that tree for the API. So the new commit carries a "No door:" line saying that. If you would rather have a screen for it, say so and I'll add one.
The comment-width message is a note, not a failure. gate --fix changed nothing, and the nightly rewrap on main will handle that line.
The feature is unchanged: GET /api/v1/repos/:owner/:name/forks?tree=1 returns the nested fork tree to depth 5, truncated: true past that, and only forks the reader can see. The plain /forks list is unchanged. test/forks-tree-api.test.ts covers it.
🤖 Generated with Claude Code
Security looks sound: visibility reuses visibleForksByParent, the answer is capped at depth 5 and 500 nodes, and the cache headers vary on identity. Three things to fix in one round:
- Box 1 asks for GET /forks itself to return {name, forks}. The tree sits behind ?tree=1 instead. If that deviation stays, the issue text needs to change and a person must agree. Otherwise make the tree reachable as the issue says, for example a separate /forks/tree route that leaves the flat contract alone.
- The 500-node cap has no test, and your own description says so. The test comment also claims the private fork is still visible to its owner, but no authenticated request checks that. Add a test for the node cap (lower the cap through a parameter) and an owner-authenticated request.
- Add docs/features/fork-tree.md with the how-to, and add the endpoint to the OpenAPI document and /llms guides, or say in the pull why not. Small cleanup: the NestedForks interface re-declares truncated and adds nothing, so use a type alias for it.
The fork tree now lives at its own route, GET /api/v1/repos/:owner/:name/forks/tree. The ?tree=1 flag is gone. It answers {name, forks:[…]} to depth five and at most 500 forks, with truncated: true on any node whose forks were cut. Only forks the reader can see appear, using visibleForksByParent as before.
The flat GET …/forks page is untouched, and a test checks it still returns items and no name. One thing for a person to confirm: issue #14138 box 1 names the bare /forks route. I took the separate route you suggested rather than amend the issue, so the issue text still says /forks.
- Node cap:
nestedForks(db, repo, user, depth, maxNodes)now takes the cap as a parameter. A new test setsmaxNodesto 1 on a repo with two forks and expects one listed andtruncatedset. Without the parameter it can't pass. - Owner view: the private-fork test now mints a read-only token for u2 and fetches the tree with it. It asserts u2 sees its own private fork and u3 beneath it, while the anonymous request still hides both.
- Type:
NestedForksis nowtype NestedForks = NestedFork. - Docs:
docs/features/fork-tree.mdhas a new "As JSON" section. The OpenAPI document gets the route throughsrc/contract/openapi/routes/getApiV1ReposOwnerNameForksTree.ts. I did not touch the/llmsguides. The API guides are built from the OpenAPI document, and I didn't opensrc/web/llms_tools.tsto confirm that, so I can't tell you the new route shows up in/llms.
bun x tsc --noEmit is clean, and the fork-tree, OpenAPI, contract and feature-orphans tests pass. scripts/fast.ts named 2014 test files, so I ran only the tests that cover this change.
To try it: curl -H "authorization: Bearer $TOKEN" $FORGE_URL/api/v1/repos/OWNER/NAME/forks/tree.
Earlier asks are met: separate /forks/tree route leaves the flat page contract alone, node cap is a parameter with a test, the owner view is tested with a token, NestedForks type tidied, docs section added under docs/features/fork-tree.md (not README), route in OpenAPI and live in the preview. Visibility reuses visibleForksByParent, so private forks and their subtrees are absent for outsiders. Non-blocking: the terminal already draws the fork tree (src/tui/screens/fork_tree.ts), so no new screen is needed for a JSON form. Non-blocking: the issue text names bare /forks; a person may want to amend it.
GET /api/v1/repos/:owner/:name/forks?tree=1now answers the fork tree as nested JSON, five generations deep. The plain/forkslist is unchanged. The new test and the existing forks and size tests pass;tscandscripts/gate.ts --fixare clean.Deviation from the issue: the issue says the bare
/forksroute should return{name, forks:[...]}. That route already returns a flat page (parent,itemswith drift,next_cursor) that the forks tests and other callers read, so I put the tree behind?tree=1. Making it the default would be a one-line change, but it would break that contract.What changed
{name:"owner/repo", forks:[{name, forks:[…]}]}. Forks beyond depth 5 are left out andtruncated: trueis set on the root and on each node whose forks were cut.src/actions/fork_nested.ts, with one query per generation. It reusesvisibleForksByParent, so it uses the same read check as the other fork views and adds no second one. A fork the caller cannot read is left out along with everything under it.truncated.src/http/api/upstream.tstakes thetree=1branch before the flat list. It sends the same weak ETag andprivate, no-cacheheaders as the flat list.test/forks-tree-api.test.tscovers three of the issue's cases and the node cap with a depth-7 chain. The three cases are a three-deep tree with a side branch, a private fork hidden from an outsider along with its child, and the depth cap with its truncated flags. The 500-fork cap has no test.Not done: no MCP change, so the MCP ceilings are untouched. I did not add
?tree=1to the OpenAPI document or the/llmsguides.Try it:
curl "$FORGE_URL/api/v1/repos/OWNER/NAME/forks?tree=1", or runbun test test/forks-tree-api.test.ts.The first push was refused by the pre-push hook, which wanted a "Try:" commit message. I added an empty commit with that message, so the pull has one extra commit.
🤖 Generated with Claude Code
Closes #14138