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

A three-deep fork chain: grandparent and grandchild see each other in the tree, and the owner of the middle fork can sever, proven in one test #12472

Merged opened this

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

Merged

scout/forge:scout/12467-a-three-deep-fork-chain-grandparent-and → main 8 commits fork 2 threads · 2 unresolved

  • Merged. scout/12467-a-three-deep-fork-chain-grandparent-and was merged into main as 2a64286.

Review

Sign in to review this change.
11 files changed +183 −11
docs/MCP.md +1 −1
@@ -599,7 +599,7 @@ answers
599599 linked production row when the app has an http(s) URL; the `new_app` card links its
600600 Production row the same way. Any other address stays plain text, never a link.
601601 The Releases card (`releases`, `ui://forge/release`) is one row per kept release, the last 10, newest first (the status line reads `last 10 of N` when there are more), its version (else its short sha), how long ago it landed, the pull that landed it (as the releases page names it, linked to that pull; a release no pull landed has the sha or version and no link, as on the page) and one word, `proven` (the keeper verified it), `unproven` (preflight failed, the keeper never cut it or is still verifying it) or `rolled back` (the keeper rolled it back). The keeper's row is looked up by sha, however old. The rows are the `items` of the tool's text, which carry the same `proof` and `pull`; `releases` with `shipped` draws the Shipped card (`ui://forge/releases`).
602 The Forks card (`fork_tree`, `ui://forge/forks`) is one row per repository you may read, nested by a `depth` field the card pads (not leading spaces, which HTML collapses); the value says how it follows: `follows on its own`, `takes updates`, `offers updates` (the card's own wording for the `offers` mode) or `off`.
602 The Forks card (`fork_tree`, `ui://forge/forks`) is one row per repository you may read, nested by a `depth` field the card pads (not leading spaces, which HTML collapses); the value says how it follows: `follows on its own`, `takes updates`, `offers updates` (the card's own wording for the `offers` mode) or `off`; a root that is a fork of a repository you cannot read adds ` · a hidden fork`.
603603 `resources/list` and `resources/read` serve one small
604604 sandboxed page, which draws the `structuredContent.card` model that the
605605 tool result carries, with `textContent` only. The model is built in
docs/features/fork-tree.md +1 −1
@@ -18,7 +18,7 @@ A repository you may not read answers "not found", as everywhere else.
1818 { "name": "fork_tree", "arguments": { "repo": "alice/app", "depth": 4, "limit": 200 } }
1919 ```
2020
21 Returns `{ root, nodes: [{ repo, parent, depth, follow, word }], truncated }`; `word` is the one word above (empty for the root). `depth` is 1-8 (default 4) generations
21 Returns `{ root, nodes: [{ repo, parent, depth, follow, word, hiddenParent? }], truncated }`; `word` is the one word above (empty for the root). `hiddenParent: true` marks a root that is a fork of a repo you cannot read: it is said as "a hidden fork" (terminal, web family tree, forks card), never named. `depth` is 1-8 (default 4) generations
2222 below the root; `limit` is 1-200 nodes (default 200). `truncated` is true when more exists than is shown.
2323
2424 - The repository asked about is always in `nodes`, with its ancestors, even when it lies deeper than `depth` or
src/actions/follow_words.ts +3
@@ -5,6 +5,9 @@ import { FORK_FOLLOW_MODES, type ForkFollowMode } from "../core/fork_follow.ts";
55 * following page alike, so they are typed once and read from here.
66 */
77
8 /** A root that is a fork of something the reader may not see: said, not left as a gap. */
9 export const HIDDEN_FORK_WORD = "a hidden fork";
10
811 /** A repository with no parent to follow, read, take from or sever. */
912 export const FOLLOWS_NOTHING = "This repository follows nothing.";
1013
src/actions/fork_tree.ts +10 −3
@@ -39,6 +39,9 @@ export interface TreeNode {
3939 readonly follow: TreeFollow;
4040 /** The same fact in the one word every door says (`FOLLOW_WORD`); empty for the root. */
4141 readonly word: string;
42 /** Set on a root that is a fork of something the caller may not read: a hidden fork, not a gap.
43 * The parent is not named. */
44 readonly hiddenParent?: true;
4245 }
4346
4447 export interface ForkTree {
@@ -102,15 +105,19 @@ export function forkTree(
102105 }
103106 level = next;
104107 }
105 const modes = forkFollowModes(db, rows.slice(1).map((r) => r.repo.id));
108 // A root that still has a parent here is a fork of one the caller cannot read.
109 const hidden = root.forkParentId !== null && !keep.has(root.forkParentId);
110 const modes = forkFollowModes(db, rows.slice(hidden ? 0 : 1).map((r) => r.repo.id));
106111 const nodes: TreeNode[] = rows.map((r) => {
107 const mode = r.parent === null ? undefined : (modes.get(r.repo.id) ?? FORK_DEFAULT_MODE);
112 const hides = hidden && r.parent === null;
113 const mode = r.parent === null && !hides ? undefined : (modes.get(r.repo.id) ?? FORK_DEFAULT_MODE);
108114 return {
109115 repo: nameOf(r.repo),
110116 parent: r.parent === null ? null : nameOf(r.parent),
111117 depth: r.depth,
112 follow: r.parent === null ? "autonomous" : treeFollow(modes.get(r.repo.id)),
118 follow: mode === undefined ? "autonomous" : treeFollow(modes.get(r.repo.id)),
113119 word: mode === undefined ? "" : FOLLOW_WORD[mode],
120 ...(hides ? { hiddenParent: true as const } : {}),
114121 };
115122 });
116123 return { root: nameOf(root), nodes, truncated };
src/contract/openapi/routes/getApiV1ReposOwnerNameFamily.ts +1 −1
@@ -4,7 +4,7 @@ export const route: Route = {
44 method: "get",
55 path: `${REPO}/family`,
66 summary:
7 "The fork tree around a repository you can read, as the MCP fork_tree tool returns it: { root, nodes: [{ repo, parent, depth, follow, word }], truncated }, from the topmost ancestor you may read down, only forks you may read; follow is autonomous (the root), take-updates, offers or dont-follow; depth 1 to 8 (default 4), limit 1 to 200 nodes; truncated is true when more exists than is shown",
7 "The fork tree around a repository you can read, as the MCP fork_tree tool returns it: { root, nodes: [{ repo, parent, depth, follow, word, hiddenParent? }], truncated }, from the topmost ancestor you may read down, only forks you may read; follow is autonomous (the root), take-updates, offers or dont-follow; depth 1 to 8 (default 4), limit 1 to 200 nodes; hiddenParent is true on a root that is a fork of a repository you may not read (the parent is not named); truncated is true when more exists than is shown",
88 auth: false,
99 role: "anonymous",
1010 query: { depth: { type: "integer", min: 1, max: 8 }, limit: limitTo(200) },
src/core/following.ts +3 −1
@@ -590,6 +590,8 @@ export interface LineageNode {
590590
591591 export interface Lineage {
592592 readonly root: LineageNode;
593 /** The root is itself a fork of a repository the viewer may not read: a hidden fork, no gap. */
594 readonly hiddenParent: boolean;
593595 /** How many repositories the tree holds, the root included. */
594596 readonly size: number;
595597 /** Whether forks were left out to stay inside the bound. */
@@ -684,5 +686,5 @@ export async function lineageOf(
684686 walk(root);
685687 const modes = forkFollowModes(forge.db, drafts.map((d) => d.repo.id));
686688 for (const d of drafts) d.mode = modes.get(d.repo.id) ?? FORK_DEFAULT_MODE;
687 return { root, size, truncated };
689 return { root, hiddenParent: top.forkParentId !== null, size, truncated };
688690 }
src/http/mcp/tools/fork_tree.ts +1 −1
@@ -4,7 +4,7 @@ import { good, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
44 /** The whole tree a repo sits in, as the caller may read it. */
55 export const tool: Tool = {
66 name: "fork_tree",
7 doc: "`{ repo, depth?, limit? }`: `{ root, nodes: [{ repo, parent, depth, follow, word }], truncated }`, the fork tree around a repo from its topmost readable ancestor down: ancestors, siblings and descendants the caller may read, nothing else; `follow` is `autonomous` (the root), `take-updates`, `offers` or `dont-follow`, `word` its plain word (follows, proposes, severed); `depth` 1-8 (default 4), `limit` 1-200 nodes (default 200); `truncated` is true when more exists than is shown; drawn as the `ui://forge/forks` card",
7 doc: "`{ repo, depth?, limit? }`: `{ root, nodes: [{ repo, parent, depth, follow, word, hiddenParent? }], truncated }`, the fork tree around a repo from its topmost readable ancestor down: ancestors, siblings and descendants the caller may read, nothing else; `follow` is `autonomous` (the root), `take-updates`, `offers` or `dont-follow`, `word` its plain word (follows, proposes, severed); `depth` 1-8 (default 4), `limit` 1-200 nodes (default 200); `hiddenParent: true` on a root that is a fork of a repo you cannot read (not named); `truncated` is true when more exists than is shown; drawn as the `ui://forge/forks` card",
88 description: "The fork tree around a repo: ancestors, siblings and descendants you may read.",
99 inputSchema: {
1010 type: "object",
src/tui/screens/fork_tree.ts +2 −1
@@ -4,6 +4,7 @@
44 * the tool does: a repo the session's person may not read has no tree.
55 */
66
7 import { HIDDEN_FORK_WORD } from "../../actions/follow_words.ts";
78 import { forkTree, type ForkTree } from "../../actions/fork_tree.ts";
89 import type { Repo } from "../../core/repos.ts";
910 import type { Ctx, Screen } from "../app/app.ts";
@@ -20,7 +21,7 @@ import { Scroll } from "./common.ts";
2021 export function treeLines(tree: ForkTree | undefined, asked: string, width = 80, viewer?: string): string[] {
2122 if (tree === undefined) return ["Nothing to show."];
2223 const lines = tree.nodes.map((n) => {
outdated

Only the terminal gets the marker. The web repo page and the forks card need it too (see the review body).

23 const follow = n.word === "" ? "" : ` ${n.word}`;
24 const follow = (n.word === "" ? "" : ` ${n.word}`) + (n.hiddenParent === true ? ` ${HIDDEN_FORK_WORD}` : "");
2425 const you = n.repo !== asked && viewer !== undefined && n.repo.startsWith(`${viewer}/`) ? " (you)" : "";
2526 return truncate(`${" ".repeat(n.depth)}${n.repo === asked ? "* " : ""}${n.repo}${you}${follow}`, width);
2627 });
src/web/pages/following.ts +2 −1
@@ -41,7 +41,7 @@ import { FOLLOW_SWITCH_LABELS, followModeWords } from "../../actions/follow_word
4141 import type { ForkFollowMode } from "../../core/fork_follow.ts";
4242 import { loadRepo, notFoundPage, repoBase, signInFirst } from "../chrome.ts";
4343 import { convergeWords, followModeOf, takeOrTell, takeWords } from "../../actions/follow.ts";
44 import { FOLLOW_WORD, FOLLOWS_NOTHING, proposeRefusalWords } from "../../actions/follow_words.ts";
44 import { FOLLOW_WORD, FOLLOWS_NOTHING, HIDDEN_FORK_WORD, proposeRefusalWords } from "../../actions/follow_words.ts";
4545 import { openProposal, proposeUpstream } from "../../actions/upstream.ts";
4646 import { convergeFollowed, followedAs, followedOf } from "../../actions/upstream_sync.ts";
4747 import { proposesViaFork } from "../../origins/fork-route.ts";
@@ -65,6 +65,7 @@ export function lineageCard(lineage: Lineage, hereId: string, viewerId?: string)
6565 here ? badge("you are here", { variant: "outline" }) : null,
6666 // The viewer's own forks say "you" in words. aria-current stays on the one row being looked at.
6767 !here && viewerId !== undefined && n.repo.ownerId === viewerId ? badge("you", { variant: "outline" }) : null,
68 depth === 0 && lineage.hiddenParent ? html`<span class="muted small">${HIDDEN_FORK_WORD}</span>` : null,
6869 n.mode === undefined ? null : html`<span class="muted small">${FOLLOW_WORD[n.mode]}</span>`,
6970 n.relation === undefined ? null : relationBadge(n.relation),
7071 ].filter((t): t is Html => t !== null);
src/web/studio/cards.ts +2 −1
@@ -10,6 +10,7 @@
1010 import { html, raw } from "../html.ts";
1111 import { CARD_PALETTE } from "../../http/mcp/card_palette.ts";
1212 import { timeAgo } from "../ui.ts";
13 import { HIDDEN_FORK_WORD } from "../../actions/follow_words.ts";
1314 import { VERB_WORDS } from "../../actions/asks_words.ts";
1415 import { span, STAGE_LABEL, verdict, type PipelineKey, type PipelineStage } from "../../flow/pipeline.ts";
1516
@@ -401,7 +402,7 @@ export function cardFor(
401402 rows.push({
402403 label: repo,
403404 ...(depth > 0 ? { depth } : {}),
404 value: text(n["word"]) || (FOLLOW_WORDS[text(n["follow"])] ?? "off"),
405 value: [text(n["word"]) || (FOLLOW_WORDS[text(n["follow"])] ?? "off"), n["hiddenParent"] === true ? HIDDEN_FORK_WORD : ""].filter((x) => x !== "").join(" · "),
405406 ...(web(origin) && slugOf(repo) ? { link: `${origin}/${repo}` } : {}),
406407 });
407408 }
test/fork-chain.test.ts added +157
@@ -0,0 +1,157 @@
1 /**
2 * A three-deep fork chain (#12467): A, B forked from A, C forked from B. Each end
3 * sees the whole chain, a private middle is a hidden fork rather than a gap, and the
4 * owner of B severs B from A with one receipted action.
5 */
6 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { FOLLOW_WORD, HIDDEN_FORK_WORD } from "../src/actions/follow_words.ts";
11 import { setFollowMode } from "../src/actions/follow.ts";
12 import { forkTree } from "../src/actions/fork_tree.ts";
13 import { commitToBranch, createRepo, forkRepo, updateRepoSettings } from "../src/actions/repos.ts";
14 import { createApp, type App } from "../src/app.ts";
15 import { listEvents } from "../src/core/events.ts";
16 import { forkRelation, lineageOf } from "../src/core/following.ts";
17 import type { Repo } from "../src/core/repos.ts";
18 import { createUser, type User } from "../src/core/users.ts";
19 import { lineageCard } from "../src/web/pages/following.ts";
20 import { cardFor } from "../src/web/studio/cards.ts";
21 import { treeLines } from "../src/tui/screens/fork_tree.ts";
22 import { promote } from "./helpers/members.ts";
23
24 const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
25 if (!r.ok) throw new Error(JSON.stringify(r.error));
26 return r.value;
27 };
28
29 let dataDir: string;
30 let app: App;
31 const users: Record<string, User> = {};
32 let a: Repo, b: Repo, c: Repo;
33
34 const full = (r: Repo) => `${r.ownerName}/${r.name}`;
35 const tree = (r: Repo, who?: User) => forkTree(app.db, r, who)!;
36 const commit = async (who: string, repo: Repo, path: string) =>
37 must(await commitToBranch(app, users[who]!, repo, { message: path, files: [{ path, content: `${path}\n` }] }));
38 const settle = async (fork: Repo, parent: Repo, state: string) => {
39 for (let i = 0; i < 60; i++) {
40 if ((await forkRelation(app, fork, parent))?.state === state) return true;
41 await Bun.sleep(50); // real-timer: polling a background relation refresh
42 }
43 return false;
44 };
45
46 beforeAll(async () => {
47 dataDir = await mkdtemp(join(tmpdir(), "forge-fork-chain-"));
48 app = createApp({ dataDir, port: 0 });
49 for (const name of ["ann", "ben", "cy", "zed"]) {
50 users[name] = must(
51 await createUser(app.db, {
52 origin: "seed",
53 trusted: true,
54 username: name,
55 email: `${name}@f.dev`,
56 password: "a-good-passphrase",
57 adminIfFirst: name === "ann",
58 }),
59 );
60 promote(app.db, users[name]!);
61 }
62 a = must(await createRepo(app, users["ann"]!, { name: "app", visibility: "public" }));
63 await commit("ann", a, "one.txt");
64 b = must(await forkRepo(app, users["ben"]!, a));
65 c = must(await forkRepo(app, users["cy"]!, b));
66 }, 60_000);
67
68 afterAll(async () => {
69 app?.close();
70 await rm(dataDir, { recursive: true, force: true });
71 });
72
73 describe("a public chain", () => {
74 test("from the grandchild it lists grandparent, parent and grandchild with depth and the follow word", () => {
75 const t = tree(c);
76 expect(t.root).toBe(full(a));
77 expect(t.nodes.map((n) => [n.repo, n.depth, n.word])).toEqual([
78 [full(a), 0, ""],
79 [full(b), 1, FOLLOW_WORD["tell-me"]],
80 [full(c), 2, FOLLOW_WORD["tell-me"]],
81 ]);
82 expect(t.nodes.some((n) => n.hiddenParent !== undefined)).toBe(false);
83 });
84
85 test("from the grandparent it lists all three, the same tree", () => {
86 expect(tree(a, users["zed"]!)).toEqual(tree(c, users["zed"]!));
87 expect(tree(a, users["zed"]!).nodes.map((n) => n.repo)).toEqual([full(a), full(b), full(c)]);
88 });
89 });
90
91 describe("a private middle", () => {
92 let top: Repo, mid: Repo, grand: Repo;
93 beforeAll(async () => {
94 top = must(await createRepo(app, users["ann"]!, { name: "pub", visibility: "public" }));
95 await commit("ann", top, "x.txt");
96 mid = must(await forkRepo(app, users["ben"]!, top, "pub"));
97 grand = must(await forkRepo(app, users["cy"]!, mid, "pub"));
98 // The middle goes private after the grandchild forked it.
99 must(await updateRepoSettings(app, users["ben"]!, mid, { visibility: "private" }));
100 });
101
102 test("an outsider sees neither the middle nor what hangs under it", () => {
103 expect(tree(top, users["zed"]!).nodes.map((n) => n.repo)).toEqual([full(top)]);
104 });
105
106 test("the grandchild's owner sees a hidden fork, not a gap, and the parent is not named", () => {
107 const t = tree(grand, users["cy"]!);
108 expect(t.nodes).toHaveLength(1);
109 expect(t.nodes[0]).toMatchObject({
110 repo: full(grand),
111 parent: null,
112 depth: 0,
113 hiddenParent: true,
114 word: FOLLOW_WORD["tell-me"],
115 });
116 expect(JSON.stringify(t)).not.toContain("ben/pub");
117 expect(treeLines(t, full(grand))[0]).toContain("a hidden fork");
118 });
119
120 test("the web family tree and the forks card say the same hidden fork", async () => {
121 const mayRead = (r: Repo) => r.id !== mid.id;
122 const lineage = await lineageOf(app, grand, mayRead);
123 expect(lineage.hiddenParent).toBe(true);
124 const html = String(lineageCard(lineage, grand.id));
125 expect(html).toContain(HIDDEN_FORK_WORD);
126 expect(html).not.toContain("ben/pub");
127 const whole = await lineageOf(app, grand, () => true);
128 expect(whole.hiddenParent).toBe(false);
129 expect(String(lineageCard(whole, grand.id))).not.toContain(HIDDEN_FORK_WORD);
130
131 const card = cardFor("fork_tree", tree(grand, users["cy"]!));
132 expect(card?.rows[0]?.value).toContain(HIDDEN_FORK_WORD);
133 expect(cardFor("fork_tree", tree(top))?.rows.some((r) => r.value.includes(HIDDEN_FORK_WORD))).toBe(false);
134 });
135 });
136
outdated

A fixed sleep followed by a negative assertion passes whether or not the refresh ran. Poll for a positive signal instead, for example the refresh's recorded base. This is also a flake risk against the direction's "tests that never flake".

137 describe("the owner of the middle severs", () => {
138 test("one receipted action: B reads severed, C still follows B, A's change no longer reaches B", async () => {
139 // Control: before severing, A's change reaches B.
140 await commit("ann", a, "two.txt");
141 expect(await settle(b, a, "synced")).toBe(true);
142
143 expect(await setFollowMode(app, users["cy"]!, b, "dont-follow")).toEqual({ ok: false, error: "forbidden" });
144 expect(must(await setFollowMode(app, users["ben"]!, b, "dont-follow"))).toBe("dont-follow");
145 const receipt = listEvents(app.db, { kind: "forge.follow_mode" }).find((e) => e.repoId === b.id);
146 expect(receipt?.actorId).toBe(users["ben"]!.id);
147 expect(receipt?.payload["mode"]).toBe("dont-follow");
148
149 const t = tree(c);
150 expect(t.nodes.find((n) => n.repo === full(b))).toMatchObject({ follow: "dont-follow", word: "severed" });
151 expect(t.nodes.find((n) => n.repo === full(c))).toMatchObject({ parent: full(b), word: FOLLOW_WORD["tell-me"] });
152
153 await commit("ann", a, "three.txt");
154 // A positive signal, polled: B reads behind A's new commit and stays behind it.
155 expect(await settle(b, a, "behind")).toBe(true);
156 });
157 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs