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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

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.

Notes

shipped production is serving it deploy 4adf612

opened this

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 and truncated: true is 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 reuses visibleForksByParent, 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.ts takes the tree=1 branch before the flat list. It sends the same weak ETag and private, no-cache headers as the flat list.
  • test/forks-tree-api.test.ts covers 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

Closes #14138

2 earlier comments · 1 event
commented

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 and truncated: true is 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 reuses visibleForksByParent, 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.ts takes the tree=1 branch before the flat list. It sends the same weak ETag and private, no-cache headers as the flat list.
  • test/forks-tree-api.test.ts covers 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

commented

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

Changes requested — before the latest push

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:

  1. 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.
  2. 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.
  3. 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.
commented

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 sets maxNodes to 1 on a repo with two forks and expects one listed and truncated set. 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: NestedForks is now type NestedForks = NestedFork.
  • Docs: docs/features/fork-tree.md has a new "As JSON" section. The OpenAPI document gets the route through src/contract/openapi/routes/getApiV1ReposOwnerNameForksTree.ts. I did not touch the /llms guides. The API guides are built from the OpenAPI document, and I didn't open src/web/llms_tools.ts to 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.

Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs