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

A fork's owner can stop following upstream in one tap and the page says it is sovereign #14884

Merged opened this

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

Merged

scout/forge:scout/14855-a-fork-s-owner-can-stop-following-upstre → main 10 commits fork 6 threads · 6 unresolved

  • Merged. scout/14855-a-fork-s-owner-can-stop-following-upstre was merged into main as 9b3c9ce.

Review

Sign in to review this change.
9 files changed +167 −9
docs/FOLLOWING.md +9
@@ -203,6 +203,15 @@ page, `POST /api/v1/repos/:owner/:name/following/take` (409, naming the
203203 converge issue), and the MCP `take_updates` tool, so the same press does the
204204 same thing at every door.
205205
206 ## Going it alone
207
208 A fork's admin severs it from its parent in Settings › Danger zone (`/-/confirm` first). The
209 confirm names the parent (only when the viewer may read it) and says what stops: no more offers go up
210 to it, no more updates come down. Only an admin may post it, from this origin; a stranger or a
211 foreign origin is refused and nothing changes. The history receipts it (`repo.detached`), and the
212 fork's home then reads "On its own since <date>" in the following card's place, with **Follow
213 upstream again** (Settings › Follow upstream) for an admin.
214
206215 ## The one sentence
207216
208217 A fork's page, MCP `forks` and `GET /api/v1/repos/:owner/:name/forks` say how far it is from its parent
docs/features/fork-sever.md added +14
@@ -0,0 +1,14 @@
1 ---
2 topic: Backups and moving
3 row: Severing a fork from its upstream
4 ---
5 # Severing a fork from its upstream
6
7 A fork's admin can stop following its parent: Settings › Danger zone › **Sever from upstream**.
8
9 - The confirm names the parent (`ann/yard`) and says what stops: updates from it and offers to it. A parent the viewer may not read is shown as "its parent".
10 - Only an admin, from this origin, can post it; anyone else is refused and nothing changes.
11 - The fork's code and history stay. The history records `repo.detached`.
12 - The fork's home then reads "On its own since <date>." in the following card's place, with **Follow upstream again** (Settings › Follow upstream) for an admin.
13
14 In the terminal it is the repository's About screen (`src/tui/screens/about.ts`): an admin presses `x` on a fork, reads the plan in the confirm and picks Detach. Both doors run `detachFromParent`, so the gate and the `repo.detached` event are the same.
outdated

Both doors: the terminal can't do this. Add the screen in src/tui/, or open a linked issue.

src/core/repo_fields.ts +1
@@ -73,6 +73,7 @@ const CREW_FIELDS = {
7373 plansNeedNod: "boolean",
7474 directionIssueId: "string|null",
7575 sealedFor: "string|null",
76 severedAt: "string|null",
7677 } as const satisfies Readonly<Record<string, string>>;
7778
7879 /** A list item as a writer gets it: the stored row whole, `detached` included. */
src/core/repos.ts +6 −1
@@ -192,6 +192,8 @@ export interface Repo {
192192 * so a list says which of its rows are frozen without a query per row.
193193 */
194194 readonly detached: RepoDetached | null;
195 /** When a fork's owner cut it loose from its parent; null when it never was (#14855). */
196 readonly severedAt: string | null;
195197 /**
196198 * Open issue and pull counts. Absent from a bare `getRepo` — a single
197199 * fetch on a hot path should not pay for a count nobody asked for — and
@@ -288,6 +290,7 @@ function toRepo(row: RepoRow): Repo {
288290 fetchError: row.fetch_error,
289291 }
290292 : null,
293 severedAt: row.origin_id === null && row.origin_full_name === null ? row.origin_detached_at : null,
291294 detached:
292295 row.origin_id === null &&
293296 row.origin_full_name !== null &&
@@ -697,7 +700,9 @@ export function forkParentFor(
697700 * breaks when the parent goes.
698701 */
699702 export function clearForkParent(db: Database, repoId: string): void {
700 db.query("UPDATE repo SET fork_parent_id = NULL WHERE id = ?1").run(repoId);
703 db.query(
704 "UPDATE repo SET fork_parent_id = NULL, origin_detached_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ?1",
705 ).run(repoId);
701706 forgetListings(db);
702707 }
703708
src/web/pages/following.ts +13
@@ -180,6 +180,19 @@ export function archivedParentLine(ctx: Ctx, repo: Repo): Html | null {
180180 </p>`;
181181 }
182182
183 /**
184 * A fork its owner cut loose reads "on its own since <date>" in the following card's place, with
185 * the way back for an admin. Null for a repository never severed or one that follows again.
186 */
187 export function onItsOwnLine(ctx: Ctx, repo: Repo): Html | null {
188 if (repo.forkParentId !== null || repo.severedAt === null) return null;
189 return html`<p class="mt small muted" data-on-its-own>
190 ${icon("fork")} On its own since ${repo.severedAt.slice(0, 10)}.${canAdmin(ctx.app.db, repo, ctx.auth.user)
191 ? html` <a href="${repoBase(repo)}/settings#upstream">Follow upstream again</a>`
192 : null}
193 </p>`;
outdated

Direction: this adds one ledger query to every repository page that follows nothing, and the pull raises two page budgets to pay for it. Reuse a query the page already makes instead and put the budgets back.

194 }
195
183196 /**
184197 * "Archived on <date>" with, for an admin, the Restore button. A repository put
185198 * away still clones, pushes and links as before; this only says so.
outdated

Principles 1 and 8: a long sentence that repeats what the confirm said. Say 'On its own since <date>.' once, in plain words, and keep the link.

src/web/pages/repo.ts +2 −1
@@ -52,6 +52,7 @@ import { keptBehind, lineageOf, MINE_ANCHOR, ownsInTree } from "../../core/follo
5252 import {
5353 archivedLine,
5454 archivedParentLine,
55 onItsOwnLine,
5556 followingCard,
5657 followingOf,
5758 type Following,
@@ -1600,7 +1601,7 @@ async function codeHome(ctx: Ctx, repo: Repo): Promise<Response> {
16001601 ${ctx.auth.user?.id === repo.ownerId && isContributionFork(ctx.app.db, repo.id)
16011602 ? contributionBar(repo)
16021603 : following === undefined
1603 ? html`${archivedParentLine(ctx, repo)}${forkBar(ctx, repo, forks)}`
1604 ? html`${archivedParentLine(ctx, repo)}${onItsOwnLine(ctx, repo)}${forkBar(ctx, repo, forks)}`
16041605 : followingCard(ctx, repo, following, { bare: true })}
16051606 ${await renderCode(scope, {
16061607 refs,
src/web/pages/search.ts +12 −6
@@ -659,12 +659,18 @@ const DESTRUCTIVE: {
659659 },
660660 {
661661 pattern: /^\/([^/]+)\/([^/]+)\/settings\/detach$/,
662 describe: (m) => ({
663 verb: "Sever from upstream",
664 title: `Detach ${m[1]}/${m[2]} from its parent?`,
665 detail: `Every object it borrows is copied into its own store and the link is dropped. ${DETACH_STAYS} ${DETACH_STOPS} It is recorded in this repository's history. ${DETACH_AGAIN}`,
666 phrase: "",
667 }),
662 describe: (m, ctx) => {
663 // The parent is named only to someone who may read it; the confirm never leaks a private one.
664 const fork = getRepo(ctx.app.db, m[1] ?? "", m[2] ?? "");
665 const parent = fork === undefined ? undefined : forkParentFor(ctx.app.db, fork, ctx.auth.user);
666 const name = parent === undefined ? "its parent" : `${parent.ownerName}/${parent.name}`;
667 return {
668 verb: "Sever from upstream",
669 title: `Detach ${m[1]}/${m[2]} from ${name}?`,
670 detail: `Every object it borrows is copied into its own store and the link is dropped. ${DETACH_STAYS} ${DETACH_STOPS} It is recorded in this repository's history. ${DETACH_AGAIN}`,
outdated

Principle 1: the new first sentence is followed by DETACH_STOPS, so the confirm says what stops twice. Keep one.

671 phrase: "",
672 };
673 },
668674 },
669675 {
670676 pattern: /^\/([^/]+)\/([^/]+)\/branches\/([^/]+)\/delete$/,
test/confirm-detach.test.ts +1 −1
@@ -74,7 +74,7 @@ test("the fork's danger zone sends Sever from upstream through the confirm page"
7474 const confirm = await fetch(`${servers.url}/-/confirm?to=${encodeURIComponent(to)}`, { headers: { cookie } });
7575 expect(confirm.status).toBe(200);
7676 const body = await confirm.text();
77 expect(body).toContain(`Detach forker/down from its parent?`);
77 expect(body).toContain("Detach forker/down from upstreamer/up?");
7878 expect(body).toContain("There is no undo, but Settings › Follow upstream can follow its address again.");
7979 expect(body).toContain(`action="${to}"`);
8080 });
test/fork-sever-page.test.ts added +109
@@ -0,0 +1,109 @@
1 /**
2 * #14855: the sever confirm names the parent and what stops; only the fork's owner, from this
3 * origin, can post it; afterwards the fork page reads "on its own" with a way to follow again.
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createApp, type App } from "../src/app.ts";
10 import { detachJob } from "../src/actions/detach.ts";
11 import { createRepo, forkRepo, type Repo } from "../src/core/repos.ts";
12 import { repoDir } from "../src/git/repos.ts";
13 import { commitFiles } from "../src/git/write.ts";
14 import { serve, type Servers } from "../src/http/server.ts";
15 import { quietLogs } from "./helpers/globals.ts";
16 import { signUpProven as signUp } from "./helpers/verified.ts";
17
18 quietLogs();
19
20 let dataDir: string;
21 let app: App;
22 let servers: Servers;
23 let fork: Repo;
24 let cookie: string;
25
26 const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
27 if (!r.ok) throw new Error(JSON.stringify(r.error));
28 return r.value;
29 };
30
31 beforeAll(async () => {
32 dataDir = await mkdtemp(join(tmpdir(), "forge-sever-page-"));
33 app = createApp({ dataDir, port: 0 });
34 servers = await serve(app);
35 const user = async (username: string) =>
36 ok(await signUp(app, { username, email: `${username}@forge.test`, password: "a-long-passphrase" }));
37 const owner = await user("upstreamer");
38 const forker = await user("forker");
39 const parent = ok(await createRepo(app.db, app.reposRoot, { ownerId: owner.id, name: "up", visibility: "public" }));
40 ok(
41 await commitFiles(repoDir(app.reposRoot, parent.ownerName, parent.name), {
42 branch: "main",
43 message: "one",
44 files: [{ path: "one.txt", content: "one" }],
45 author: { name: "T", email: "[email protected]" },
46 }),
47 );
48 fork = ok(await forkRepo(app.db, app.reposRoot, parent, forker.id, "down"));
49 const signin = await fetch(`${servers.url}/signin`, {
50 method: "POST",
51 headers: { origin: servers.url },
52 body: new URLSearchParams({ username: "forker", password: "a-long-passphrase" }),
53 redirect: "manual",
54 });
55 cookie = (signin.headers.get("set-cookie") ?? "").split(";")[0]!;
56 }, 30_000);
57
58 afterAll(async () => {
59 servers.stop();
60 app.close();
61 await rm(dataDir, { recursive: true, force: true });
62 });
63
64 test("the confirm names the parent and what stops; a stranger and a cross-origin post are refused; afterwards the fork reads on its own", async () => {
65 const base = `/${fork.ownerName}/${fork.name}`;
66 const to = `${base}/settings/detach`;
67 const confirm = await (await fetch(`${servers.url}/-/confirm?to=${encodeURIComponent(to)}`, { headers: { cookie } })).text();
68 expect(confirm).toContain("Detach forker/down from upstreamer/up?");
69 expect(confirm).toContain("Updates from the parent and offers to it stop.");
70 expect(confirm.split("offers to it stop").length - 1).toBe(1);
71
72 const form = (origin: string, c: string) => ({
73 method: "POST",
74 headers: { origin, cookie: c },
75 body: new URLSearchParams(),
76 redirect: "manual" as const,
77 });
78 // A stranger: signed in, not the fork's owner.
79 ok(await signUp(app, { username: "stranger", email: "[email protected]", password: "a-long-passphrase" }));
80 const si = await fetch(`${servers.url}/signin`, {
81 method: "POST",
82 headers: { origin: servers.url },
83 body: new URLSearchParams({ username: "stranger", password: "a-long-passphrase" }),
84 redirect: "manual",
85 });
86 const strangerCookie = (si.headers.get("set-cookie") ?? "").split(";")[0]!;
87 const refused = await fetch(`${servers.url}${to}`, form(servers.url, strangerCookie));
outdated

Box 3: the stranger's response is never asserted. Check its status, and that detachJob(fork.id) is undefined and the page is unchanged, straight after this post.

88 expect(refused.status).toBeGreaterThanOrEqual(400);
89 expect(detachJob(fork.id)).toBeUndefined();
90 expect((await (await fetch(`${servers.url}${base}`, { headers: { cookie } })).text())).not.toContain("data-on-its-own");
91 // A foreign origin, even from the owner.
outdated

This await Promise.resolve() does nothing useful. Remove it.

92 const cross = await fetch(`${servers.url}${to}`, form("https://evil.example", cookie));
93 expect(cross.status).toBeGreaterThanOrEqual(400);
94 expect(detachJob(fork.id)).toBeUndefined();
95 const stillFork = await (await fetch(`${servers.url}${base}`, { headers: { cookie } })).text();
96 expect(stillFork).not.toContain("data-on-its-own");
97
98 // The owner, same origin: severs.
99 await fetch(`${servers.url}${to}`, form(servers.url, cookie));
100 await detachJob(fork.id)?.done;
101 const after = await (await fetch(`${servers.url}${base}`, { headers: { cookie } })).text();
102 expect(after).toContain("data-on-its-own");
103 expect(after).toContain("On its own since");
104 expect(after).toMatch(/On its own since \d{4}-\d{2}-\d{2}\./);
105 expect(after).toContain(`${base}/settings#upstream`);
106 const strangerView = await (await fetch(`${servers.url}${base}`, { headers: { cookie: strangerCookie } })).text();
107 expect(strangerView).toContain("data-on-its-own");
108 expect(strangerView).not.toContain("Follow upstream again");
109 }, 30_000);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs