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

An owner severs a fork from its upstream with one confirmed action, and the tree shows it severed #13453

Merged opened this

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

Merged

scout/forge:scout/13427-an-owner-severs-a-fork-from-its-upstream → main 6 commits fork 2 threads · 2 unresolved

  • Merged. scout/13427-an-owner-severs-a-fork-from-its-upstream was merged into main as 69a756b.

Review

Sign in to review this change.
10 files changed +124 −10
docs/features/detach.md +1 −1
@@ -6,5 +6,5 @@ A fork borrows its parent's objects through git alternates, and the forge shows
66 - **Detach.** A repository admin opens *Settings › Danger zone › Detach from parent*. From an archived parent's quiet line it is the "detach from it" link. The card names the parent only to an admin who may still read it. The `repo.detached` event carries the parent's id, never its name. The detach repacks the fork so it owns every object it borrowed (`detachFork`, the same step deleting a parent takes), drops the alternates link, then forgets the parent. The repack runs in the background, and the card says it is running and since when. If it fails, git's line stays on the card and nothing changes. There is no undo.
77 - **Terminal.** On a fork's About card (`I`), an admin presses `x`. The terminal shows the plan, and the detach starts only after it is confirmed. A `detach` row shows the phase, as the card does.
88 - **MCP.** `detach { repo }` returns the plan: the parent, and whether the fork still borrows objects. `detach { repo, dryRun: false }` starts the detach, and needs an admin token. Calling it again shows the `phase` until the fork has no `parent`. An agent is refused, as with `archive`.
9 - **What it says.** Every door (the confirm page, the Danger zone section, the terminal's plan, the MCP dry run) says the same two lines from `actions/detach_words.ts`: the code and its history stay, with the branches, issues and pulls; updates from the parent and offers to it stop. Following cannot be set up again on the same repository, since the parent is forgotten; fork the upstream afresh to follow it.
9 - **What it says.** Every door (the confirm page, the Danger zone section, the terminal's plan, the MCP dry run) says the same two lines from `actions/detach_words.ts`: the code and its history stay, with the branches, issues and pulls; updates from the parent and offers to it stop. There is no undo, but the severed repository can follow the upstream's address again: its admin opens *Settings › Follow upstream* (the Following card is on forks only, so it is not there). That follows by address, as for any repository; it does not restore the fork link. In the fork tree the severed repository's own row reads `severed`; its former parent's tree does not list it.
1010 - **Receipt.** When the detach lands, the repository's history gets a `repo.detached` row: "severed a fork from its upstream: code and history kept, updates and offers stopped", with who and when. After confirming, the page's flash says the repack runs on its own and the history records it when it lands.
docs/features/fork-tree.md +1 −1
@@ -51,6 +51,6 @@ Right opens a branch (or steps in), Left closes it (or steps out), Home/End jump
5151 ("level 2") and how it follows as a word (`follows`, `proposes`: `FOLLOW_WORD`), never colour alone;
5252 the tree is at most four levels deep, so indentation is at most three steps. The row itself is the `treeitem`
5353 (it takes focus, so it says its level and state); the "level N" text is hidden from screen readers, which hear `aria-level`.
54 A child cannot report a severed mode, so that word is not drawn. Test: `test/family-a11y.test.ts`.
54 A repository whose owner severed it from its upstream reads `severed` on its own row (the ledger holds a `repo.detached` event); a plain root that never was a fork reads as before. A child cannot report a severed mode, so that word is not drawn. Test: `test/family-a11y.test.ts`.
5555
5656 Each fork in the forks page's tree and in the terminal's tree and forks screens also says its mode in words (`FOLLOW_PHRASE` in `src/actions/follow_words.ts`): `follows automatically`, `proposes only`, or `severed · no longer follows`, the last drawn dimmed. Test: `test/fork-tree-mode.test.ts`.
src/actions/detach.ts +2 −2
@@ -16,7 +16,7 @@ import { detachFork, hasAlternates, repoDir } from "../git/repos.ts";
1616 import { createLog } from "../kernel/log.ts";
1717 import { err, ok, type Result } from "../kernel/result.ts";
1818 import { requireRepoAdmin } from "./access.ts";
19 import { DETACH_STAYS, DETACH_STOPS } from "./detach_words.ts";
19 import { DETACH_AGAIN, DETACH_STAYS, DETACH_STOPS } from "./detach_words.ts";
2020
2121 const log = createLog("detach");
2222
@@ -131,7 +131,7 @@ function failureLine(stderr: string): string {
131131 /** The plan in one sentence, for the terminal's confirm and the MCP. */
132132 export function detachPlanWords(plan: DetachPlan): string {
133133 const parent = plan.parent ?? "its parent";
134 return `${plan.borrows ? `Copies every object it borrows from ${parent} into its own store, drops the link, then forgets` : `Borrows nothing from ${parent}; forgets`} the parent. ${DETACH_STAYS} ${DETACH_STOPS} There is no undo.`;
134 return `${plan.borrows ? `Copies every object it borrows from ${parent} into its own store, drops the link, then forgets` : `Borrows nothing from ${parent}; forgets`} the parent. ${DETACH_STAYS} ${DETACH_STOPS} ${DETACH_AGAIN}`;
135135 }
136136
137137 /** Where a detach stands, in words; null when none is under way or failed. */
src/actions/detach_words.ts +5
@@ -12,3 +12,8 @@ export const DETACH_STOPS = "Updates from the parent and offers to it stop.";
1212 export const DETACH_RECEIPT = "severed a fork from its upstream: code and history kept, updates and offers stopped";
1313 /** A fork's line in a chain when its link was cut: the chain stops there. */
1414 export const SEVERED_LINE = "Severed from its upstream.";
15 /**
16 * No undo, and the way back: any repository's admin follows an address from Settings, under Follow
outdated

Principle 8/1: this promises a 'Following card' on a repository that has just lost its parent. Verify on the preview that such a card exists there, or reword to the route that does. Also it repeats the 'no undo' line right before it; fold them into one sentence.

17 * upstream.
18 */
19 export const DETACH_AGAIN = "There is no undo, but Settings › Follow upstream can follow its address again.";
src/actions/fork_tree.ts +11
@@ -110,6 +110,9 @@ export function forkTree(
110110 const modes = forkFollowModes(db, rows.slice(hidden ? 0 : 1).map((r) => r.repo.id));
111111 const nodes: TreeNode[] = rows.map((r) => {
112112 const hides = hidden && r.parent === null;
113 // A root whose link the owner cut reads "severed", not nothing.
114 if (r.parent === null && !hides && severedRoot(db, r.repo))
115 return { repo: nameOf(r.repo), parent: null, depth: r.depth, follow: "dont-follow" as const, word: FOLLOW_WORD["dont-follow"] };
113116 const mode = r.parent === null && !hides ? undefined : (modes.get(r.repo.id) ?? FORK_DEFAULT_MODE);
114117 return {
115118 repo: nameOf(r.repo),
@@ -126,3 +129,11 @@ export function forkTree(
126129 /** A stored mode as the tree names it: `tell-me`, stored or by default, is `offers`. */
127130 const treeFollow = (mode: string | undefined): TreeFollow =>
128131 mode === "take-updates" || mode === "dont-follow" ? mode : "offers";
132
133 /**
134 * Whether this repository was cut from its upstream: it names no parent and the ledger holds the
135 * severing.

One event-table query per root on every tree build; fine for one root, but add a test for a repo with a parent_id of null that was never detached (reads as before) so the 'severed' word cannot leak onto plain roots.

136 */
137 const severedRoot = (db: Database, repo: Repo): boolean =>
138 repo.forkParentId === null &&
139 db.query("SELECT 1 FROM event WHERE repo_id = ?1 AND kind = 'repo.detached' LIMIT 1").get(repo.id) !== null;
src/web/pages/detach.ts +2 −2
@@ -8,7 +8,7 @@
88 */
99
1010 import { detachFromParent, detachJob, type DetachJob } from "../../actions/detach.ts";
11 import { DETACH_STAYS, DETACH_STOPS } from "../../actions/detach_words.ts";
11 import { DETACH_AGAIN, DETACH_STAYS, DETACH_STOPS } from "../../actions/detach_words.ts";
1212 import { forkParentFor, type Repo } from "../../core/repos.ts";
1313 import type { User } from "../../core/users.ts";
1414 import type { Ctx } from "../../http/context.ts";
@@ -67,7 +67,7 @@ export function detachBlock({ name, action, job }: DetachView): Html {
6767 <p>
6868 Copies what this fork borrows from <strong>${name}</strong> into its
6969 own store and forgets the parent. ${DETACH_STAYS} ${DETACH_STOPS}
70 It is recorded in this repository's history. There is no undo.
70 It is recorded in this repository's history. ${DETACH_AGAIN}
7171 </p>
7272 <div class="form-actions">
7373 ${confirmAction({ action, verb: "Detach from parent" })}
src/web/pages/search.ts +2 −2
@@ -11,7 +11,7 @@
1111 */
1212
1313 import { returnTo, withReturn } from "../return_to.ts";
14 import { DETACH_STAYS, DETACH_STOPS } from "../../actions/detach_words.ts";
14 import { DETACH_AGAIN, DETACH_STAYS, DETACH_STOPS } from "../../actions/detach_words.ts";
1515 import { DISCONNECT_DETAIL } from "../../actions/origin_words.ts";
1616 import { strangerCodeSearch } from "../../http/strangers.ts";
1717 import { search } from "../../actions/search.ts";
@@ -614,7 +614,7 @@ const DESTRUCTIVE: {
614614 describe: (m) => ({
615615 verb: "Detach from parent",
616616 title: `Detach ${m[1]}/${m[2]} from its parent?`,
617 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. There is no undo.`,
617 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}`,
618618 phrase: "",
619619 }),
620620 },
test/confirm-detach.test.ts +1 −1
@@ -75,7 +75,7 @@ test("the fork's danger zone sends Detach from parent through the confirm page",
7575 expect(confirm.status).toBe(200);
7676 const body = await confirm.text();
7777 expect(body).toContain(`Detach forker/down from its parent?`);
78 expect(body).toContain("There is no undo.");
78 expect(body).toContain("There is no undo, but Settings › Follow upstream can follow its address again.");
7979 expect(body).toContain(`action="${to}"`);
8080 });
8181
test/danger-language.test.ts +1 −1
@@ -86,7 +86,7 @@ test("the detach shows its plan with its parent named", async () => {
8686 const m = main(await (await danger(forker)).text());
8787 const detach = m.slice(m.indexOf('id="detach"'), m.indexOf('id="delete"'));
8888 expect(detach).toContain("<strong>upstreamer/up</strong>");
89 expect(detach).toContain("There is no undo.");
89 expect(detach).toContain("There is no undo, but Settings › Follow upstream");
9090 expect(detach).toContain(`href="/-/confirm?to=${encodeURIComponent(`${base()}/settings/detach`)}"`);
9191 });
9292
test/fork-sever.test.ts added +98
@@ -0,0 +1,98 @@
1 /**
2 * #13427: after an owner severs a fork, an upstream change proposes nothing
3 * down to it, the fork's own tree reads "severed", and the words offer the
4 * way back (follow it again). A sibling that stayed attached is the control:
5 * the same push does reach it.
6 */
7 import { afterAll, beforeAll, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
13 import { detachFromParent, detachJob, detachPlanWords } from "../src/actions/detach.ts";
14 import { DETACH_AGAIN } from "../src/actions/detach_words.ts";
15 import { forkTree } from "../src/actions/fork_tree.ts";
16 import { forkRepo as coreFork, getRepo, type Repo } from "../src/core/repos.ts";
17 import { createUser, type User } from "../src/core/users.ts";
18 import { runGit } from "../src/git/env.ts";
19 import { repoDir } from "../src/git/repos.ts";
20 import { quietLogs } from "./helpers/globals.ts";
21
22 quietLogs();
23
24 let dataDir = "";
25 let app: App;
26 let alice: User;
27 let bob: User;
28 let parent: Repo;
29 const cells = process.env["FORGE_CELLS"];
30
31 const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
32 if (!r.ok) throw new Error(JSON.stringify(r.error));
33 return r.value;
34 };
35 const commit = async (repo: Repo, path: string) =>
36 ok(await commitToBranch(app, alice, repo, { message: path, files: [{ path, content: `${path}\n` }] }));
37 const tip = async (repo: Repo): Promise<string> => {
38 const r = await runGit(["rev-parse", "refs/heads/main"], { cwd: repoDir(app.reposRoot, repo.ownerName, repo.name) });
39 if (!r.ok) throw new Error(r.error.stderr);
40 return r.value.trim();
41 };
42 const diverged: string[] = [];
43
44 beforeAll(async () => {
45 process.env["FORGE_CELLS"] = "off";
46 dataDir = await mkdtemp(join(tmpdir(), "forge-fork-sever-"));
47 app = createApp({ dataDir, port: 0 });
48 alice = ok(await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }));
49 bob = ok(await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" }));
50 parent = ok(await createRepo(app, alice, { name: "root", visibility: "public" }));
51 await commit(parent, "a.txt");
52 app.bus.subscribe((e) => {
53 if (e.kind === "fork.diverged" && e.repoId !== null) diverged.push(e.repoId);
54 });
55 });
56
57 afterAll(async () => {
58 app.close();
59 if (cells === undefined) delete process.env["FORGE_CELLS"];
60 else process.env["FORGE_CELLS"] = cells;
61 await rm(dataDir, { recursive: true, force: true });
62 });
63
64 test("a severed fork is told nothing when its upstream changes; an attached sibling is", async () => {
65 const severed = ok(await forkRepo(app, alice, parent, "cut"));
66 const kept = ok(await coreFork(app.db, app.reposRoot, parent, bob.id, "kept"));
67 await commit(severed, "mine.txt");
68 await commit(kept, "mine.txt");
69
70 const planned = ok(await detachFromParent(app, alice, getRepo(app.db, "alice", "cut")!, true));
71 expect(planned.dryRun).toBe(true);
72 expect(getRepo(app.db, "alice", "cut")!.forkParentId).not.toBeNull();
73 ok(await detachFromParent(app, alice, getRepo(app.db, "alice", "cut")!, false));
74 await detachJob(severed.id)?.done;
75 expect(getRepo(app.db, "alice", "cut")!.forkParentId).toBeNull();
76
77 const before = await tip(severed);
78 await commit(parent, "upstream.txt");
79 // The follow-on runs off the event; give it the same turns it needs for the sibling.
80 for (let i = 0; i < 100 && !diverged.includes(kept.id); i++) await Bun.sleep(20); // real-timer: polls for a git event follow-on that has no injectable clock
81 expect(diverged).toContain(kept.id);
82 expect(diverged).not.toContain(severed.id);
83 expect(await tip(severed)).toBe(before);
84 });
85
86 test("a root that was never a fork reads no severed word", async () => {
87 const plain = ok(await createRepo(app, alice, { name: "plainroot", visibility: "public" }));
88 expect(forkTree(app.db, getRepo(app.db, "alice", plain.name)!, alice)!.nodes[0]!.word).toBe("");
89 });
90
91 test("the severed fork's own tree row reads severed; the words offer the way back", () => {
92 const cut = getRepo(app.db, "alice", "cut")!;
93 const tree = forkTree(app.db, cut, alice)!;
94 expect(tree.nodes[0]).toMatchObject({ repo: "alice/cut", follow: "dont-follow", word: "severed" });
95 const attached = forkTree(app.db, getRepo(app.db, "bob", "kept")!, alice)!;
96 expect(attached.nodes.find((n) => n.repo === "alice/root")!.word).toBe("");
97 expect(detachPlanWords({ parent: "alice/root", borrows: false, dryRun: true })).toContain(DETACH_AGAIN);
98 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs