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

A fork can be severed from its upstream by its owner in one confirmed action that keeps all history #14550

Merged opened this

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

Merged

scout/forge:scout/14482-a-fork-can-be-severed-from-its-upstream → main 6 commits fork 1 thread · 1 unresolved

  • Merged. scout/14482-a-fork-can-be-severed-from-its-upstream was merged into main as 8b34986.

Review

Sign in to review this change.
11 files changed +60 −14
docs/MCP.md +3
@@ -56,6 +56,7 @@ the directory differ.
5656
5757 Five tools need no token, for the same reach as their HTTP doors: `report`,
5858 `offer`, `start`, `explore` and `search` (`TOKEN_FREE_TOOLS` in `src/core/mcp_card.ts`).
59
5960 `offer` (`{ repo, title, body?, patch }`, or `{ receipt }` to read an offer's state) calls `fileOffer`, the action behind
6061 `POST /api/v1/repos/{owner}/{name}/offers`, with the same refusal words (the 422
6162 reasons, `rate_limited`, `queue_full`; a private repository answers `not_found`);
@@ -68,6 +69,8 @@ account sees. `tools/list` still needs a token (its 401 is what starts a
6869 client's OAuth sign-in); the open tools are named in `/llms.txt`, the server
6970 card (`tokenFreeTools`) and `/api/v1/here`.
7071
72 `fork` also takes `{ repo, action: "sever", dryRun? }`: the same severing Settings offers (the `detach` tool's plan and words), so an owner or their agent leaves the upstream by either door; `dryRun` is true unless `false`, and the real call needs an admin token.
73
7174 The complete list, with schemas, is MCP `tools/list` called with a token.
7275 `/llms.txt`, under "## MCP tools", lists only the tools open without a token (one line each, from its `doc`) and counts the rest, pointing on to `tools/list`; signed in, it lists the tools that token may call (a read-only token omits the writes it cannot make; admin tools need an admin account and an admin-scope token). It carries an ETag that changes only when its words do; a stranger's read is public for five minutes and answers `If-None-Match` with 304, a token's is private.
7376
docs/features/detach.md +1 −1
@@ -7,7 +7,7 @@ row: Detach a fork from its parent
77 A fork borrows its parent's objects through git alternates, and the forge shows how far it stands from that parent. When the parent is put away for good, the fork can stand alone.
88
99 - **Archived parent.** When a fork's parent is archived, the fork's page shows one quiet line, "forked from owner/name (archived)", in place of the Following card. There is no ahead/behind count, nothing to take, and no Propose upstream. The archived repository's forks page lists its forks by name, with no count against them.
10 - **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.
10 - **Detach.** A repository admin opens *Settings › Danger zone › Sever from upstream*. 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.
1111 - **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.
1212 - **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`.
1313 - **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.
src/http/mcp/tools/fork.ts +6 −2
@@ -10,25 +10,29 @@ import { isSafeOid } from "../../../git/guard.ts";
1010 import { resolveOid } from "../../../git/merge.ts";
1111 import { commitLog } from "../../../git/read.ts";
1212 import { repoDir } from "../../../git/repos.ts";
13 import { tool as detachTool } from "./detach.ts";
1314 import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
1415
1516 /** The MCP door to `POST /api/v1/repos/:owner/:name/forks`: the same action, the same refusals. */
1617 export const tool: Tool = {
1718 name: "fork",
18 doc: "`{ repo, name? }`: fork a repository you can read into your account, as POST `/api/v1/repos/:owner/:name/forks` does. For a guest this is Help build this: a public fork that runs nothing, to change with `write_file` or git and send back with `open_pull`; a refusal says what to do instead. `{ repo, action: \"offer\", commit }` sends a full commit id of your fork to its parent as a pull and returns its receipt `{ receipt, state: sent|seen|taken|declined|withdrawn, says, reason, upstream, url }`; `{ action: \"receipt\", receipt }` reads it again, `{ action: \"withdraw\", receipt }` takes a pending offer back (commits stay; not once taken; offerer or fork owner only). Page: `/offers/<receipt>`",
19 doc: "`{ repo, name? }`: fork a repository you can read into your account,. For a guest this is Help build this: a public fork that runs nothing, to change with `write_file` or git and send back with `open_pull`. `{ repo, action: \"offer\", commit }` sends a full commit id of your fork to its parent as a pull and returns its receipt `{ receipt, state: sent|seen|taken|declined|withdrawn, says, reason, upstream, url }`; `{ action: \"receipt\", receipt }` reads it again, `{ action: \"withdraw\", receipt }` takes a pending offer back (not once taken). Page: `/offers/<receipt>`. `{ repo, action: \"sever\", dryRun? }` severs your fork from its upstream: dryRun (default) says what stops and stays; `dryRun: false` with an admin token does it",

Non-blocking: the trimmed doc has a stray "into your account,." and no longer says it mirrors POST /api/v1/repos/:owner/:name/forks or that a refusal says what to do. Fix the punctuation and restore the short pointer if the llms.txt budget allows.

1920 description: "Fork a repository into your account; `action` offer sends a fork's commit upstream, receipt reads it.",
2021 inputSchema: {
2122 type: "object",
2223 properties: {
2324 repo: REPO_ARG,
2425 name: { type: "string" },
25 action: { type: "string", enum: ["offer", "receipt", "withdraw"] },
26 action: { type: "string", enum: ["offer", "receipt", "withdraw", "sever"] },
2627 commit: { type: "string", maxLength: 40 },
28 dryRun: { type: "boolean" },
2729 receipt: { type: "string", maxLength: 32 },
2830 },
2931 },
3032 writes: true,
33 readsWhen: (args) => args["action"] === "sever" && args["dryRun"] !== false,
3134 async run(ctx, user, args) {
35 if (args["action"] === "sever") return detachTool.run(ctx, user, args);
3236 if (args["action"] === "receipt") {
3337 const got = readForkOffer(ctx.app.db, user, str(args["receipt"]));
3438 return got === undefined ? bad("not_found", "no such receipt for you") : good({ ...got, says: got.words });
src/tui/screens/about.ts +2 −2
@@ -260,7 +260,7 @@ export function aboutScreen(
260260 ? [binding(["V"], repo?.visibility === "public" ? "make private" : "make public")]
261261 : []),
262262 ...(mayDetach() && detachJob(repo!.id)?.phase !== "repacking"
263 ? [binding(["x"], "detach from parent")]
263 ? [binding(["x"], "sever from upstream")]
264264 : []),
265265 ...(offered === null
266266 ? []
@@ -437,7 +437,7 @@ export function aboutScreen(
437437 if (!plan.ok) return ctx.toast("that could not be detached", "danger");
438438 ctx.push(
439439 confirmScreen(ctx, screen, {
440 title: "Detach from parent",
440 title: "Sever from upstream",
441441 body: [detachPlanWords(plan.value)],
442442 actions: [{ label: "Detach" }, { label: "Cancel" }],
443443 onChoose: (i) => {
src/web/pages/detach.ts +3 −3
@@ -1,5 +1,5 @@
11 /**
2 * Settings › Danger zone › "Detach from parent" (#7452). The section is the
2 * Settings › Danger zone › "Sever from upstream" (#7452). The section is the
33 * plan — what the detach copies and what it ends — and its button starts
44 * it. While the repack runs the section says so and since when; a failure
55 * stays on it with git's line until the next try. The button goes
@@ -70,10 +70,10 @@ export function detachBlock({ name, action, job }: DetachView): Html {
7070 It is recorded in this repository's history. ${DETACH_AGAIN}
7171 </p>
7272 <div class="form-actions">
73 ${confirmAction({ action, verb: "Detach from parent" })}
73 ${confirmAction({ action, verb: "Sever from upstream" })}
7474 </div>`;
7575 return html`<section class="settings-block" id="detach">
76 <h2>Detach from parent</h2>
76 <h2>Sever from upstream</h2>
7777 ${body}
7878 </section>`;
7979 }
src/web/pages/search.ts +1 −1
@@ -660,7 +660,7 @@ const DESTRUCTIVE: {
660660 {
661661 pattern: /^\/([^/]+)\/([^/]+)\/settings\/detach$/,
662662 describe: (m) => ({
663 verb: "Detach from parent",
663 verb: "Sever from upstream",
664664 title: `Detach ${m[1]}/${m[2]} from its parent?`,
665665 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}`,
666666 phrase: "",
test/confirm-detach.test.ts +2 −2
@@ -1,5 +1,5 @@
11 /**
2 * #7978: "Detach from parent" has no undo, so the fork's danger zone links
2 * #7978: "Sever from upstream" has no undo, so the fork's danger zone links
33 * it to /-/confirm, which names the fork and posts the detach on the second
44 * step exactly as the button used to.
55 */
@@ -64,7 +64,7 @@ afterAll(async () => {
6464 await rm(dataDir, { recursive: true, force: true });
6565 });
6666
67 test("the fork's danger zone sends Detach from parent through the confirm page", async () => {
67 test("the fork's danger zone sends Sever from upstream through the confirm page", async () => {
6868 const base = `/${fork.ownerName}/${fork.name}`;
6969 const to = `${base}/settings/detach`;
7070 const danger = await (await fetch(`${servers.url}${base}/settings/danger`, { headers: { cookie } })).text();
test/danger-language.test.ts +1 −1
@@ -75,7 +75,7 @@ const danger = async (cookie: string) => fetch(`${servers.url}${base()}/settings
7575 test("the danger zone is two settings-blocks under h2s, no card", async () => {
7676 const m = main(await (await danger(forker)).text());
7777 expect(m).not.toContain('class="card');
78 expect(m).toMatch(/<section class="settings-block" id="detach">\s*<h2>Detach from parent<\/h2>/);
78 expect(m).toMatch(/<section class="settings-block" id="detach">\s*<h2>Sever from upstream<\/h2>/);
7979 expect(m).toMatch(/<section class="settings-block" id="delete">\s*<h2>Delete this repository<\/h2>/);
8080 // what goes and what survives
8181 expect(m).toMatch(/Forks survive; this repository does\s+not\./);
test/fork-detach.test.ts +1 −1
@@ -198,7 +198,7 @@ describe("detach from parent", () => {
198198 expect(home).toContain(`href="${base}/settings/danger#detach"`);
199199 const danger = await (await fetch(`${servers.url}${base}/settings/danger`, { headers: { cookie } })).text();
200200 expect(danger).toContain(`href="/-/confirm?to=${encodeURIComponent(`${base}/settings/detach`)}"`);
201 expect(danger).toContain("Detach from parent");
201 expect(danger).toContain("Sever from upstream");
202202
203203 const post = (origin: string) =>
204204 fetch(`${servers.url}${base}/settings/detach`, {
test/fork-sever.test.ts +39
@@ -96,3 +96,42 @@ test("the severed fork's own tree row reads severed; the words offer the way bac
9696 expect(attached.nodes.find((n) => n.repo === "alice/root")!.word).toBe("");
9797 expect(detachPlanWords({ parent: "alice/root", borrows: false, dryRun: true })).toContain(DETACH_AGAIN);
9898 });
99
100 test("the MCP fork tool's sever action plans in the page's words, severs, and the former parent's offers no longer list the fork", async () => {
101 const { serve } = await import("../src/http/server.ts");
102 const { createToken } = await import("../src/core/tokens.ts");
103 const { forkOffers } = await import("../src/core/fork_offers.ts");
104 const { visibleForks } = await import("../src/core/repos.ts");
105 const { DETACH_STAYS, DETACH_STOPS } = await import("../src/actions/detach_words.ts");
106 const servers = await serve(app);
107 const token = createToken(app.db, alice.id, "admin", "admin").token;
108 const call = async (args: Record<string, unknown>): Promise<string> => {
109 const res = await fetch(`${servers.url}/mcp`, {
110 method: "POST",
111 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
112 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "fork", arguments: args } }),
113 });
114 const body = (await res.json()) as { result: { content: { text: string }[] } };
115 return body.result.content[0]!.text;
116 };
117 try {
118 const fork = ok(await forkRepo(app, alice, parent, "mcpcut"));
119 await commit(fork, "x.txt");
120 const plan = await call({ repo: "alice/mcpcut", action: "sever" });
121 expect(plan).toContain(DETACH_STAYS);
122 expect(plan).toContain(DETACH_STOPS);
123 expect(getRepo(app.db, "alice", "mcpcut")!.forkParentId).not.toBeNull();
124
125 await call({ repo: "alice/mcpcut", action: "sever", dryRun: false });
126 await detachJob(fork.id)?.done;
127 expect(getRepo(app.db, "alice", "mcpcut")!.forkParentId).toBeNull();
128 // The fork feed's receipt line: the MCP path writes the same repo.detached event Settings does.
129 const receipts = app.db.query("SELECT 1 FROM event WHERE repo_id = ?1 AND kind = 'repo.detached'").all(fork.id);
130 expect(receipts).toHaveLength(1);
131 expect(forkTree(app.db, getRepo(app.db, "alice", "mcpcut")!, alice, app)!.nodes[0]!.word).toBe("severed");
132 expect(forkOffers(app.db, parent, alice)).toEqual([]);
133 expect(visibleForks(app.db, parent.id, alice).map((f) => f.name)).not.toContain("mcpcut");
134 } finally {
135 servers.stop();
136 }
137 });
test/tui-about-detach.test.ts +1 −1
@@ -130,7 +130,7 @@ test("an archived parent offers no o, and x plans, confirms, then detaches", asy
130130
131131 c.press("x");
132132 await until("the plan again", () => c.pushed.length === 2);
133 expect(c.pushed[1]!.title).toBe("Detach from parent");
133 expect(c.pushed[1]!.title).toBe("Sever from upstream");
134134 c.pushed[1]!.key!({ key: "enter" } as never);
135135 // The repack may land between two polls, so wait for the outcome, not
136136 // for the job to be seen running (the next test reads the running row).

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs