Public: anyone can read this; the crew can change it.
An agent can read the whole fork tree of an app in one call: ancestors, siblings and descendants with how each follows its upstream #10412
scout/forge:scout/10388-an-agent-can-read-the-whole-fork-tree-of → main 4 commits fork
6 files
changed +440
−3
docs/FOLLOWING.md +21
| @@ -296,3 +296,24 @@ The check cell's memory is on the same page under **Check cell**, and in the ter | ||
| 296 | 296 | the secret once on its own screen; `x` asks before it revokes the one under |
| 297 | 297 | the cursor ("Revoke the token for <child>?", Keep selected): `y` revokes, |
| 298 | 298 | `n`, esc or enter keeps it. |
| 299 | ||
| 300 | ## The tree as data | |
| 301 | ||
| 302 | `GET /api/v1/repos/:owner/:name/forks?tree=1` (and the MCP `forks` tool with | |
| 303 | `tree: true`, same words) answers the family around a repository as | |
| 304 | `{ root, nodes, total, max_depth, truncated, next_cursor }`. `nodes` run | |
| 305 | ancestors (root first), the repository (`self`), its `sibling`s, then its | |
| 306 | `descendant`s level by level. Each node: `repo`, `parent`, `relation`, `depth` | |
| 307 | (ancestors count down, siblings are 0), `follow`, `ahead`, `behind`, | |
| 308 | `updatedAt` (default branch last moved) and `lastShip` (last merged pull). | |
| 309 | ||
| 310 | `follow` is `take-updates` when the fork chose that mode, else `autonomous` | |
| 311 | when its crew works autonomously, else `offers` (told of updates, offers its | |
| 312 | own work upward); `null` on a root. Limits: `depth` 1-4 (default 4), at most | |
| 313 | 1,000 siblings and descendants (`truncated` says when more exist), pages of | |
| 314 | `limit` 1-200 (default 50) continued by `cursor` = the last `next_cursor`. | |
| 315 | ||
| 316 | A fork the caller cannot read is left out with everything beneath it, and | |
| 317 | `total`, `truncated` and the pages are counted after that. Standing is kept by | |
| 318 | the two tips read from ref files, so a warm tree runs no git (200 forks under | |
| 319 | 50 ms, asserted in `test/fork-tree-api.test.ts`). |
src/actions/fork_tree.ts added +234
| @@ -0,0 +1,234 @@ | ||
| 1 | /** | |
| 2 | * The fork tree of an app as data (#10388): the ancestors of a repository, | |
| 3 | * itself, its siblings and its descendants, each with how it follows its | |
| 4 | * upstream. One answer for the API (`GET …/forks?tree=1`) and the MCP | |
| 5 | * (`forks` with `tree: true`), in the same words. | |
| 6 | * | |
| 7 | * Visibility is settled first: a fork the caller cannot read is dropped | |
| 8 | * with everything beneath it, and every count (`total`, `truncated`) is | |
| 9 | * taken from what is left, so no number tells of a hidden fork. | |
| 10 | */ | |
| 11 | ||
| 12 | import type { App } from "../app.ts"; | |
| 13 | import { DEFAULT_MODE, type FollowMode } from "../spawn/chain.ts"; | |
| 14 | import { forkParentFor, visibleForks, visibleForksByParent, type Repo } from "../core/repos.ts"; | |
| 15 | import type { User } from "../core/users.ts"; | |
| 16 | import { divergence } from "../git/branches.ts"; | |
| 17 | import { runGit } from "../git/env.ts"; | |
| 18 | import { isSafeRef } from "../git/guard.ts"; | |
| 19 | import { refTip } from "../git/read.ts"; | |
| 20 | import { repoDir } from "../git/repos.ts"; | |
| 21 | ||
| 22 | /** Levels of descendants listed under the repository asked about. */ | |
| 23 | export const MAX_TREE_DEPTH = 4; | |
| 24 | /** Siblings and descendants listed in all; past it `truncated` is true. */ | |
| 25 | export const MAX_TREE_NODES = 1000; | |
| 26 | /** Ancestors walked up. */ | |
| 27 | const MAX_ANCESTORS = 8; | |
| 28 | export const TREE_PAGE_DEFAULT = 50; | |
| 29 | export const TREE_PAGE_MAX = 200; | |
| 30 | ||
| 31 | export type TreeRelation = "ancestor" | "self" | "sibling" | "descendant"; | |
| 32 | /** `take-updates`: moves with its parent; `offers`: told of updates, offers its own work; `autonomous`: its crew works on its own. `null`: a root. */ | |
| 33 | export type TreeFollow = "take-updates" | "offers" | "autonomous"; | |
| 34 | ||
| 35 | export interface TreeNode { | |
| 36 | readonly repo: string; | |
| 37 | readonly parent: string | null; | |
| 38 | readonly relation: TreeRelation; | |
| 39 | /** Levels from the repository asked about: ancestors count down (-1 is its parent), siblings are 0. */ | |
| 40 | readonly depth: number; | |
| 41 | readonly follow: TreeFollow | null; | |
| 42 | readonly ahead: number | null; | |
| 43 | readonly behind: number | null; | |
| 44 | /** When the default branch last moved (ISO), or null. */ | |
| 45 | readonly updatedAt: string | null; | |
| 46 | /** When the last pull merged into it (ISO), or null. */ | |
| 47 | readonly lastShip: string | null; | |
| 48 | } | |
| 49 | ||
| 50 | export interface TreeAnswer { | |
| 51 | readonly root: string; | |
| 52 | readonly nodes: TreeNode[]; | |
| 53 | /** Every node the caller may see, listed or not. */ | |
| 54 | readonly total: number; | |
| 55 | readonly max_depth: number; | |
| 56 | /** True when siblings and descendants past `MAX_TREE_NODES` were left out. */ | |
| 57 | readonly truncated: boolean; | |
| 58 | readonly next_cursor: string | null; | |
| 59 | } | |
| 60 | ||
| 61 | interface Entry { | |
| 62 | readonly repo: Repo; | |
| 63 | readonly parent: Repo | undefined; | |
| 64 | readonly relation: TreeRelation; | |
| 65 | readonly depth: number; | |
| 66 | } | |
| 67 | ||
| 68 | const nameOf = (r: Repo): string => `${r.ownerName}/${r.name}`; | |
| 69 | ||
| 70 | /** The nodes in order: ancestors from the root down, itself, its siblings, then descendants level by level. */ | |
| 71 | function entriesOf(app: App, repo: Repo, viewer: User | undefined, maxDepth: number): { entries: Entry[]; truncated: boolean } { | |
| 72 | const up: Entry[] = []; | |
| 73 | let child = repo; | |
| 74 | for (let i = 1; i <= MAX_ANCESTORS; i++) { | |
| 75 | const parent = forkParentFor(app.db, child, viewer); | |
| 76 | if (parent === undefined) break; | |
| 77 | const above = forkParentFor(app.db, parent, viewer); | |
| 78 | up.unshift({ repo: parent, parent: above, relation: "ancestor", depth: -i }); | |
| 79 | child = parent; | |
| 80 | } | |
| 81 | const parent = forkParentFor(app.db, repo, viewer); | |
| 82 | const entries: Entry[] = [...up, { repo, parent, relation: "self", depth: 0 }]; | |
| 83 | let room = MAX_TREE_NODES; | |
| 84 | let truncated = false; | |
| 85 | const take = (e: Entry): boolean => { | |
| 86 | if (room === 0) return (truncated = true), false; | |
| 87 | room--; | |
| 88 | entries.push(e); | |
| 89 | return true; | |
| 90 | }; | |
| 91 | if (parent !== undefined) | |
| 92 | for (const s of visibleForks(app.db, parent.id, viewer)) | |
| 93 | if (s.id !== repo.id && !take({ repo: s, parent, relation: "sibling", depth: 0 })) break; | |
| 94 | let level: Repo[] = [repo]; | |
| 95 | for (let depth = 1; depth <= maxDepth && level.length > 0; depth++) { | |
| 96 | const by = visibleForksByParent(app.db, level, viewer); | |
| 97 | const next: Repo[] = []; | |
| 98 | for (const p of level) | |
| 99 | for (const f of by.get(p.id) ?? []) { | |
| 100 | if (!take({ repo: f, parent: p, relation: "descendant", depth })) return { entries, truncated }; | |
| 101 | next.push(f); | |
| 102 | } | |
| 103 | level = next; | |
| 104 | } | |
| 105 | return { entries, truncated }; | |
| 106 | } | |
| 107 | ||
| 108 | interface Standing { | |
| 109 | readonly ahead: number | null; | |
| 110 | readonly behind: number | null; | |
| 111 | readonly pushedAt: string | null; | |
| 112 | } | |
| 113 | ||
| 114 | /** | |
| 115 | * A fork's standing is a pure function of the two tips, which are read from | |
| 116 | * the ref files (no process): a tree whose forks have not moved costs no git | |
| 117 | * run at all. Bounded; a full cache is emptied rather than tracked. | |
| 118 | */ | |
| 119 | const standings = new Map<string, Standing>(); | |
| 120 | const STANDINGS_MAX = 4_000; | |
| 121 | const UNKNOWN: Standing = { ahead: null, behind: null, pushedAt: null }; | |
| 122 | ||
| 123 | async function standingOf(app: App, fork: Repo, parent: Repo | undefined): Promise<Standing> { | |
| 124 | if (parent === undefined || parent.archivedAt !== null || !isSafeRef(fork.defaultBranch)) return UNKNOWN; | |
| 125 | const forkDir = repoDir(app.reposRoot, fork.ownerName, fork.name); | |
| 126 | const [base, tip] = await Promise.all([ | |
| 127 | refTip(repoDir(app.reposRoot, parent.ownerName, parent.name), `refs/heads/${parent.defaultBranch}`), | |
| 128 | refTip(forkDir, `refs/heads/${fork.defaultBranch}`), | |
| 129 | ]); | |
| 130 | if (base === undefined || tip === undefined) return UNKNOWN; | |
| 131 | const key = `${base}:${tip}`; | |
| 132 | const hit = standings.get(key); | |
| 133 | if (hit !== undefined) return hit; | |
| 134 | const [drift, at] = await Promise.all([ | |
| 135 | divergence(forkDir, base, tip), | |
| 136 | runGit(["log", "-1", "--format=%cI", tip], { cwd: forkDir }), | |
| 137 | ]); | |
| 138 | const standing: Standing = { ...drift, pushedAt: at.ok ? at.value.trim() || null : null }; | |
| 139 | if (standings.size >= STANDINGS_MAX) standings.clear(); | |
| 140 | standings.set(key, standing); | |
| 141 | return standing; | |
| 142 | } | |
| 143 | ||
| 144 | /** The last merged pull of each repository, one read for the page. */ | |
| 145 | function lastShips(app: App, ids: readonly string[]): Map<string, string> { | |
| 146 | const out = new Map<string, string>(); | |
| 147 | if (ids.length === 0) return out; | |
| 148 | const rows = app.db | |
| 149 | .query<{ repo_id: string; at: string }, string[]>( | |
| 150 | `SELECT i.repo_id AS repo_id, MAX(p.merged_at) AS at | |
| 151 | FROM issue i JOIN pull p ON p.issue_id = i.id | |
| 152 | WHERE i.repo_id IN (${ids.map(() => "?").join(",")}) AND i.kind = 'pull' AND p.merged_at IS NOT NULL | |
| 153 | GROUP BY i.repo_id`, | |
| 154 | ) | |
| 155 | .all(...ids); | |
| 156 | for (const r of rows) out.set(r.repo_id, r.at); | |
| 157 | return out; | |
| 158 | } | |
| 159 | ||
| 160 | export const SHIPS_PLAN_SQL = `EXPLAIN QUERY PLAN SELECT i.repo_id, MAX(p.merged_at) FROM issue i JOIN pull p ON p.issue_id = i.id WHERE i.repo_id IN ('x') AND i.kind = 'pull' AND p.merged_at IS NOT NULL GROUP BY i.repo_id`; | |
| 161 | ||
| 162 | /** The follow mode of each repository that has one set, one read for the page. */ | |
| 163 | function followModes(app: App, ids: readonly string[]): Map<string, FollowMode> { | |
| 164 | const out = new Map<string, FollowMode>(); | |
| 165 | if (ids.length === 0) return out; | |
| 166 | const rows = app.db | |
| 167 | .query<{ repo_id: string; mode: FollowMode }, string[]>( | |
| 168 | `SELECT repo_id, mode FROM fork_follow WHERE repo_id IN (${ids.map(() => "?").join(",")})`, | |
| 169 | ) | |
| 170 | .all(...ids); | |
| 171 | for (const r of rows) out.set(r.repo_id, r.mode); | |
| 172 | return out; | |
| 173 | } | |
| 174 | ||
| 175 | function followOf(modes: Map<string, FollowMode>, e: Entry): TreeFollow | null { | |
| 176 | if (e.parent === undefined) return null; | |
| 177 | if ((modes.get(e.repo.id) ?? DEFAULT_MODE) === "take-updates") return "take-updates"; | |
| 178 | return e.repo.autonomy === "autonomous" ? "autonomous" : "offers"; | |
| 179 | } | |
| 180 | ||
| 181 | export type TreeError = "invalid_depth" | "invalid_limit" | "invalid_cursor"; | |
| 182 | ||
| 183 | /** The tree around `repo` as the viewer may see it, one page of it. */ | |
| 184 | export async function forkTreeOf( | |
| 185 | app: App, | |
| 186 | viewer: User | undefined, | |
| 187 | repo: Repo, | |
| 188 | opts: { depth?: unknown; limit?: unknown; cursor?: unknown }, | |
| 189 | ): Promise<{ ok: true; value: TreeAnswer } | { ok: false; error: TreeError }> { | |
| 190 | const depth = opts.depth ?? MAX_TREE_DEPTH; | |
| 191 | if (typeof depth !== "number" || !Number.isInteger(depth) || depth < 1 || depth > MAX_TREE_DEPTH) | |
| 192 | return { ok: false, error: "invalid_depth" }; | |
| 193 | const limit = opts.limit ?? TREE_PAGE_DEFAULT; | |
| 194 | if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > TREE_PAGE_MAX) | |
| 195 | return { ok: false, error: "invalid_limit" }; | |
| 196 | const { entries, truncated } = entriesOf(app, repo, viewer, depth); | |
| 197 | let start = 0; | |
| 198 | if (opts.cursor !== undefined) { | |
| 199 | const at = typeof opts.cursor === "string" ? entries.findIndex((e) => nameOf(e.repo) === opts.cursor) : -1; | |
| 200 | if (at < 0) return { ok: false, error: "invalid_cursor" }; | |
| 201 | start = at + 1; | |
| 202 | } | |
| 203 | const page = entries.slice(start, start + limit); | |
| 204 | const ships = lastShips(app, page.map((e) => e.repo.id)); | |
| 205 | const modes = followModes(app, page.map((e) => e.repo.id)); | |
| 206 | const nodes = await Promise.all( | |
| 207 | page.map(async (e): Promise<TreeNode> => { | |
| 208 | const s = await standingOf(app, e.repo, e.parent); | |
| 209 | return { | |
| 210 | repo: nameOf(e.repo), | |
| 211 | parent: e.parent === undefined ? null : nameOf(e.parent), | |
| 212 | relation: e.relation, | |
| 213 | depth: e.depth, | |
| 214 | follow: followOf(modes, e), | |
| 215 | ahead: s.ahead, | |
| 216 | behind: s.behind, | |
| 217 | updatedAt: s.pushedAt, | |
| 218 | lastShip: ships.get(e.repo.id) ?? null, | |
| 219 | }; | |
| 220 | }), | |
| 221 | ); | |
| 222 | const more = start + limit < entries.length; | |
| 223 | return { | |
| 224 | ok: true, | |
| 225 | value: { | |
| 226 | root: nameOf(repo), | |
| 227 | nodes, | |
| 228 | total: entries.length, | |
| 229 | max_depth: depth, | |
| 230 | truncated, | |
| 231 | next_cursor: more ? nameOf(page[page.length - 1]!.repo) : null, | |
| 232 | }, | |
| 233 | }; | |
| 234 | } |
src/core/repos.ts +1 −1
| @@ -714,7 +714,7 @@ const forksOfMany = (db: Database, ids: readonly string[]): Repo[] => | ||
| 714 | 714 | .map(toRepo); |
| 715 | 715 | |
| 716 | 716 | /** The visible forks of these parents, grouped by parent id: one query. */ |
| 717 | function visibleForksByParent( | |
| 717 | export function visibleForksByParent( | |
| 718 | 718 | db: Database, |
| 719 | 719 | parents: readonly Repo[], |
| 720 | 720 | viewer: User | undefined, |
src/http/api/upstream.ts +27
| @@ -21,6 +21,9 @@ import { storageLimitMessage } from "../../core/storage.ts"; | ||
| 21 | 21 | import { getFollow } from "../../core/upstream_follow.ts"; |
| 22 | 22 | import { holds, weakEtag } from "../etag.ts"; |
| 23 | 23 | import { loadRepo, pageParams, slicePage } from "../api.ts"; |
| 24 | import { forkTreeOf } from "../../actions/fork_tree.ts"; | |
| 25 | import type { Repo } from "../../core/repos.ts"; | |
| 26 | import type { Ctx } from "../context.ts"; | |
| 24 | 27 | import type { Handler } from "../context.ts"; |
| 25 | 28 | import { apiError, body, json, notFound, requireScope, respondAccess, str } from "../respond.ts"; |
| 26 | 29 | import type { Router } from "../router.ts"; |
| @@ -84,6 +87,7 @@ export function upstreamRoutes(router: Router<Handler>): void { | ||
| 84 | 87 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 85 | 88 | const repo = loadRepo(ctx); |
| 86 | 89 | if (!repo) return notFound(); |
| 90 | if (ctx.url.searchParams.get("tree") === "1") return forkTreeResponse(ctx, repo); | |
| 87 | 91 | const page = pageParams(ctx); |
| 88 | 92 | if (page instanceof Response) return page; |
| 89 | 93 | const rows = timePhase(ctx.request, "forks", () => visibleForks(ctx.app.db, repo.id, ctx.auth.user)); |
| @@ -145,3 +149,26 @@ export function upstreamRoutes(router: Router<Handler>): void { | ||
| 145 | 149 | return json(forked.value, 201); |
| 146 | 150 | }); |
| 147 | 151 | } |
| 152 | ||
| 153 | const TREE_REFUSALS = { | |
| 154 | invalid_depth: "depth is a whole number from 1 to 4", | |
| 155 | invalid_limit: "limit is a whole number from 1 to 200", | |
| 156 | invalid_cursor: "cursor is the next_cursor of a previous page", | |
| 157 | } as const; | |
| 158 | ||
| 159 | /** `?tree=1`: the ancestors, siblings and descendants of a repository, each with how it follows its upstream. */ | |
| 160 | async function forkTreeResponse(ctx: Ctx, repo: Repo): Promise<Response> { | |
| 161 | const q = ctx.url.searchParams; | |
| 162 | const num = (k: string): unknown => (q.has(k) ? (/^[0-9]{1,4}$/.test(q.get(k)!) ? Number(q.get(k)) : NaN) : undefined); | |
| 163 | const tree = await timePhaseAsync(ctx.request, "drift", () => | |
| 164 | forkTreeOf(ctx.app, ctx.auth.user, repo, { depth: num("depth"), limit: num("limit"), cursor: q.get("cursor") ?? undefined }), | |
| 165 | ); | |
| 166 | if (!tree.ok) return apiError(tree.error, 422, TREE_REFUSALS[tree.error]); | |
| 167 | return timePhase(ctx.request, "render", () => { | |
| 168 | const text = JSON.stringify(tree.value); | |
| 169 | const etag = weakEtag(text); | |
| 170 | const headers = { etag, "cache-control": "private, no-cache", vary: "authorization, cookie" }; | |
| 171 | if (holds(ctx.request, etag)) return new Response(null, { status: 304, headers }); | |
| 172 | return new Response(text, { headers: { "content-type": "application/json", ...headers } }); | |
| 173 | }); | |
| 174 | } |
src/http/mcp/tools/forks.ts +9 −2
| @@ -1,11 +1,12 @@ | ||
| 1 | 1 | import { driftOfForks, MAX_RANKED_FORKS, type RankedFork } from "../../../actions/forks.ts"; |
| 2 | 2 | import { forkParentFor, visibleForks, type Repo } from "../../../core/repos.ts"; |
| 3 | import { forkTreeOf } from "../../../actions/fork_tree.ts"; | |
| 3 | 4 | import { pageRows } from "../page.ts"; |
| 4 | import { good, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; | |
| 5 | import { bad, good, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; | |
| 5 | 6 | |
| 6 | 7 | export const tool: Tool = { |
| 7 | 8 | name: "forks", |
| 8 | doc: "`{ repo, limit?, cursor? }`: `{ parent, forks: [{ repo, ahead, behind, updatedAt }], next_cursor }`, the forks the caller may see in the order `/:owner/:name/forks` lists them, each with its commits ahead of and behind this one (`null` when git cannot say); `limit` 1-200 (default 50), `cursor` the last `next_cursor` (null on the last page); drift is read for the page only", | |
| 9 | doc: "`{ repo, limit?, cursor? }`: `{ parent, forks: [{ repo, ahead, behind, updatedAt }], next_cursor }`, the forks the caller may see in the order `/:owner/:name/forks` lists them, each with its commits ahead of and behind this one (`null` when git cannot say); `limit` 1-200 (default 50), `cursor` the last `next_cursor` (null on the last page); drift is read for the page only; `tree: true` (`depth` 1-4) answers `{ root, nodes: [{ repo, parent, relation, depth, follow, ahead, behind, updatedAt, lastShip }], total, max_depth, truncated, next_cursor }` for ancestors, siblings and descendants (`follow`: take-updates, offers, autonomous)", | |
| 9 | 10 | description: "A repo's forks you may see, paged by limit and cursor (next_cursor), each with commits ahead and behind.", |
| 10 | 11 | inputSchema: { |
| 11 | 12 | type: "object", |
| @@ -13,6 +14,8 @@ export const tool: Tool = { | ||
| 13 | 14 | repo: REPO_ARG, |
| 14 | 15 | limit: { type: "integer", minimum: 1, maximum: 200 }, |
| 15 | 16 | cursor: { type: "string" }, |
| 17 | tree: { type: "boolean" }, | |
| 18 | depth: { type: "integer", minimum: 1, maximum: 4 }, | |
| 16 | 19 | }, |
| 17 | 20 | required: ["repo"], |
| 18 | 21 | }, |
| @@ -20,6 +23,10 @@ export const tool: Tool = { | ||
| 20 | 23 | async run(ctx, user, args) { |
| 21 | 24 | const repo = repoArg(ctx, user, args); |
| 22 | 25 | if (isAnswer(repo)) return repo; |
| 26 | if (args["tree"] === true) { | |
| 27 | const tree = await forkTreeOf(ctx.app, user, repo, { depth: args["depth"], limit: args["limit"], cursor: args["cursor"] }); | |
| 28 | return tree.ok ? good(tree.value) : bad(tree.error, `${tree.error}: see docs/FOLLOWING.md, "The tree as data"`); | |
| 29 | } | |
| 23 | 30 | const parent = forkParentFor(ctx.app.db, repo, user); |
| 24 | 31 | const paged = pageRows(visibleForks(ctx.app.db, repo.id, user), (f) => f.id, args); |
| 25 | 32 | if (!paged.ok) return paged; |
test/fork-tree-api.test.ts added +148
| @@ -0,0 +1,148 @@ | ||
| 1 | /** The fork tree as data (#10388): the API and the MCP answer the same shape; hidden forks change no count. */ | |
| 2 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 3 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts"; | |
| 7 | import { setFollowMode } from "../src/actions/follow.ts"; | |
| 8 | import { SHIPS_PLAN_SQL } from "../src/actions/fork_tree.ts"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { createToken } from "../src/core/tokens.ts"; | |
| 11 | import { createUser, type User } from "../src/core/users.ts"; | |
| 12 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 13 | import { quietLogs } from "./helpers/globals.ts"; | |
| 14 | import { promote } from "./helpers/members.ts"; | |
| 15 | import { statements } from "./helpers/statements.ts"; | |
| 16 | import { expectWork } from "./helpers/work.ts"; | |
| 17 | ||
| 18 | quietLogs(); | |
| 19 | ||
| 20 | let dataDir = ""; | |
| 21 | let app: App, servers: Servers; | |
| 22 | const users: Record<string, User> = {}; | |
| 23 | const tokens: Record<string, string> = {}; | |
| 24 | ||
| 25 | const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => { | |
| 26 | if (!r.ok) throw new Error(JSON.stringify(r.error)); | |
| 27 | return r.value; | |
| 28 | }; | |
| 29 | ||
| 30 | beforeAll(async () => { | |
| 31 | dataDir = await mkdtemp(join(tmpdir(), "forge-fork-tree-api-")); | |
| 32 | app = createApp({ dataDir, port: 0 }); | |
| 33 | servers = await serve(app); | |
| 34 | for (const name of ["alice", "acme", "pat", "zed"]) { | |
| 35 | users[name] = must(await createUser(app.db, { origin: "seed", trusted: true, username: name, email: `${name}@f.dev`, password: "a-good-passphrase", adminIfFirst: name === "alice" })); | |
| 36 | promote(app.db, users[name]!); | |
| 37 | tokens[name] = createToken(app.db, users[name]!.id, "t", "admin").token; | |
| 38 | } | |
| 39 | }, 30_000); | |
| 40 | ||
| 41 | afterAll(async () => { | |
| 42 | servers.stop(); | |
| 43 | app.close(); | |
| 44 | await rm(dataDir, { recursive: true, force: true }); | |
| 45 | }); | |
| 46 | ||
| 47 | const get = async (path: string, who?: string) => { | |
| 48 | const res = await fetch(`${servers.url}${path}`, { headers: who ? { authorization: `Bearer ${tokens[who]}` } : {} }); | |
| 49 | return { status: res.status, body: (await res.json()) as any }; | |
| 50 | }; | |
| 51 | const mcp = async (args: Record<string, unknown>, who: string) => { | |
| 52 | const res = await fetch(`${servers.url}/mcp`, { | |
| 53 | method: "POST", | |
| 54 | headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${tokens[who]}` }, | |
| 55 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "forks", arguments: args } }), | |
| 56 | }); | |
| 57 | const body = (await res.json()) as any; | |
| 58 | const text = body.result.content[0].text as string; | |
| 59 | return body.result.isError === true ? { error: text.split(":")[0]! } : JSON.parse(text); | |
| 60 | }; | |
| 61 | ||
| 62 | test("a three-level tree reads from any node: my forge, an organization, a person; the API and the MCP agree", async () => { | |
| 63 | const root = must(await createRepo(app, users["alice"]!, { name: "app", visibility: "public" })); | |
| 64 | await commitToBranch(app, users["alice"]!, root, { message: "one", files: [{ path: "a.txt", content: "x\n" }] }); | |
| 65 | const org = must(await forkRepo(app, users["acme"]!, root)); | |
| 66 | const person = must(await forkRepo(app, users["pat"]!, org)); | |
| 67 | await commitToBranch(app, users["pat"]!, person, { message: "own", files: [{ path: "p.txt", content: "y\n" }] }); | |
| 68 | must(await setFollowMode(app, users["acme"]!, org, "take-updates")).valueOf(); | |
| 69 | ||
| 70 | const top = await get("/api/v1/repos/alice/app/forks?tree=1"); | |
| 71 | expect(top.status).toBe(200); | |
| 72 | expect(top.body.root).toBe("alice/app"); | |
| 73 | expect(top.body.nodes.map((n: any) => [n.repo, n.relation, n.depth, n.parent])).toEqual([ | |
| 74 | ["alice/app", "self", 0, null], | |
| 75 | ["acme/app", "descendant", 1, "alice/app"], | |
| 76 | ["pat/app", "descendant", 2, "acme/app"], | |
| 77 | ]); | |
| 78 | const [, o, p] = top.body.nodes; | |
| 79 | expect(o.follow).toBe("take-updates"); | |
| 80 | expect(p.follow).toBe("offers"); | |
| 81 | expect(p.ahead).toBe(1); | |
| 82 | expect(p.updatedAt).not.toBeNull(); | |
| 83 | expect(top.body.nodes[0].follow).toBeNull(); | |
| 84 | expect(top.body.total).toBe(3); | |
| 85 | ||
| 86 | const mid = await get("/api/v1/repos/acme/app/forks?tree=1"); | |
| 87 | expect(mid.body.nodes.map((n: any) => [n.repo, n.relation])).toEqual([["alice/app", "ancestor"], ["acme/app", "self"], ["pat/app", "descendant"]]); | |
| 88 | const leaf = await get("/api/v1/repos/pat/app/forks?tree=1"); | |
| 89 | expect(leaf.body.nodes.map((n: any) => n.relation)).toEqual(["ancestor", "ancestor", "self"]); | |
| 90 | ||
| 91 | expect(await mcp({ repo: "acme/app", tree: true }, "alice")).toEqual(mid.body); | |
| 92 | // Without tree, the flat list is as it was. | |
| 93 | expect((await get("/api/v1/repos/alice/app/forks")).body.items.length).toBe(1); | |
| 94 | }); | |
| 95 | ||
| 96 | test("a private fork the caller cannot read is omitted with its subtree and changes no count", async () => { | |
| 97 | const root = must(await createRepo(app, users["alice"]!, { name: "lib", visibility: "public" })); | |
| 98 | must(await forkRepo(app, users["acme"]!, root)); | |
| 99 | const hidden = must(await forkRepo(app, users["pat"]!, root, undefined, { visibility: "private" })); | |
| 100 | must(await forkRepo(app, users["alice"]!, hidden, "under-hidden")); | |
| 101 | const seen = await get("/api/v1/repos/alice/lib/forks?tree=1", "zed"); | |
| 102 | expect(seen.body.nodes.map((n: any) => n.repo)).toEqual(["alice/lib", "acme/lib"]); | |
| 103 | expect(seen.body.total).toBe(2); | |
| 104 | expect(JSON.stringify(seen.body)).not.toContain("pat/lib"); | |
| 105 | expect(JSON.stringify(await mcp({ repo: "alice/lib", tree: true }, "zed"))).not.toContain("pat/lib"); | |
| 106 | const owner = await get("/api/v1/repos/alice/lib/forks?tree=1", "pat"); | |
| 107 | expect(owner.body.total).toBe(3); // alice's private fork under pat's is hers alone | |
| 108 | }); | |
| 109 | ||
| 110 | test("limit pages with next_cursor; bad depth, limit and cursor are refused", async () => { | |
| 111 | const first = await get("/api/v1/repos/alice/app/forks?tree=1&limit=2"); | |
| 112 | expect(first.body.nodes.length).toBe(2); | |
| 113 | expect(first.body.next_cursor).toBe("acme/app"); | |
| 114 | const next = await get(`/api/v1/repos/alice/app/forks?tree=1&limit=2&cursor=${first.body.next_cursor}`); | |
| 115 | expect(next.body.nodes.map((n: any) => n.repo)).toEqual(["pat/app"]); | |
| 116 | expect(next.body.next_cursor).toBeNull(); | |
| 117 | expect((await get("/api/v1/repos/alice/app/forks?tree=1&depth=9")).status).toBe(422); | |
| 118 | expect((await get("/api/v1/repos/alice/app/forks?tree=1&limit=0")).status).toBe(422); | |
| 119 | expect((await get("/api/v1/repos/alice/app/forks?tree=1&cursor=nope")).status).toBe(422); | |
| 120 | const shallow = await get("/api/v1/repos/alice/app/forks?tree=1&depth=1"); | |
| 121 | expect(shallow.body.nodes.length).toBe(2); | |
| 122 | expect(shallow.body.max_depth).toBe(1); | |
| 123 | }); | |
| 124 | ||
| 125 | test("the last-ship read walks an index", () => { | |
| 126 | const plan = app.db.query(SHIPS_PLAN_SQL).all().map((r: any) => r.detail).join("\n"); | |
| 127 | expect(plan).not.toMatch(/SCAN issue/); | |
| 128 | }); | |
| 129 | ||
| 130 | test("a warm answer on a tree of 200 forks costs a bounded number of statements", async () => { | |
| 131 | const root = must(await createRepo(app, users["alice"]!, { name: "big", visibility: "public" })); | |
| 132 | await commitToBranch(app, users["alice"]!, root, { message: "one", files: [{ path: "a.txt", content: "x\n" }] }); | |
| 133 | for (let i = 0; i < 200; i++) { | |
| 134 | const u = must(await createUser(app.db, { origin: "seed", trusted: true, username: `u${i}`, email: `u${i}@f.dev`, password: "a-good-passphrase" })); | |
| 135 | promote(app.db, u); | |
| 136 | must(await forkRepo(app, u, root)); | |
| 137 | } | |
| 138 | const url = "/api/v1/repos/alice/big/forks?tree=1&limit=200"; | |
| 139 | const cold = await get(url); | |
| 140 | expect(cold.body.nodes.length).toBe(200); | |
| 141 | expect(cold.body.total).toBe(201); | |
| 142 | expect(cold.body.next_cursor).not.toBeNull(); | |
| 143 | const n = await statements(app.db, async () => { | |
| 144 | await get(url); | |
| 145 | }); | |
| 146 | // One statement per fork is the visibility check (canRead, shared with every fork list); the page itself adds a handful, not another per fork. | |
| 147 | expectWork(n, { max: 200 + 15 }); | |
| 148 | }, 120_000); |
new above
offline