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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14482-a-fork-can-be-severed-from-its-upstream → main 6 commits fork 1 thread · 1 unresolved
11 files
changed +60
−14
docs/MCP.md +3
| @@ -56,6 +56,7 @@ the directory differ. | ||
| 56 | 56 | |
| 57 | 57 | Five tools need no token, for the same reach as their HTTP doors: `report`, |
| 58 | 58 | `offer`, `start`, `explore` and `search` (`TOKEN_FREE_TOOLS` in `src/core/mcp_card.ts`). |
| 59 | ||
| 59 | 60 | `offer` (`{ repo, title, body?, patch }`, or `{ receipt }` to read an offer's state) calls `fileOffer`, the action behind |
| 60 | 61 | `POST /api/v1/repos/{owner}/{name}/offers`, with the same refusal words (the 422 |
| 61 | 62 | 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 | ||
| 68 | 69 | client's OAuth sign-in); the open tools are named in `/llms.txt`, the server |
| 69 | 70 | card (`tokenFreeTools`) and `/api/v1/here`. |
| 70 | 71 | |
| 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 | ||
| 71 | 74 | The complete list, with schemas, is MCP `tools/list` called with a token. |
| 72 | 75 | `/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. |
| 73 | 76 |
docs/features/detach.md +1 −1
| @@ -7,7 +7,7 @@ row: Detach a fork from its parent | ||
| 7 | 7 | 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. |
| 8 | 8 | |
| 9 | 9 | - **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. | |
| 11 | 11 | - **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. |
| 12 | 12 | - **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`. |
| 13 | 13 | - **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"; | ||
| 10 | 10 | import { resolveOid } from "../../../git/merge.ts"; |
| 11 | 11 | import { commitLog } from "../../../git/read.ts"; |
| 12 | 12 | import { repoDir } from "../../../git/repos.ts"; |
| 13 | import { tool as detachTool } from "./detach.ts"; | |
| 13 | 14 | import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; |
| 14 | 15 | |
| 15 | 16 | /** The MCP door to `POST /api/v1/repos/:owner/:name/forks`: the same action, the same refusals. */ |
| 16 | 17 | export const tool: Tool = { |
| 17 | 18 | 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", | |
| 19 | 20 | description: "Fork a repository into your account; `action` offer sends a fork's commit upstream, receipt reads it.", |
| 20 | 21 | inputSchema: { |
| 21 | 22 | type: "object", |
| 22 | 23 | properties: { |
| 23 | 24 | repo: REPO_ARG, |
| 24 | 25 | name: { type: "string" }, |
| 25 | action: { type: "string", enum: ["offer", "receipt", "withdraw"] }, | |
| 26 | action: { type: "string", enum: ["offer", "receipt", "withdraw", "sever"] }, | |
| 26 | 27 | commit: { type: "string", maxLength: 40 }, |
| 28 | dryRun: { type: "boolean" }, | |
| 27 | 29 | receipt: { type: "string", maxLength: 32 }, |
| 28 | 30 | }, |
| 29 | 31 | }, |
| 30 | 32 | writes: true, |
| 33 | readsWhen: (args) => args["action"] === "sever" && args["dryRun"] !== false, | |
| 31 | 34 | async run(ctx, user, args) { |
| 35 | if (args["action"] === "sever") return detachTool.run(ctx, user, args); | |
| 32 | 36 | if (args["action"] === "receipt") { |
| 33 | 37 | const got = readForkOffer(ctx.app.db, user, str(args["receipt"])); |
| 34 | 38 | 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( | ||
| 260 | 260 | ? [binding(["V"], repo?.visibility === "public" ? "make private" : "make public")] |
| 261 | 261 | : []), |
| 262 | 262 | ...(mayDetach() && detachJob(repo!.id)?.phase !== "repacking" |
| 263 | ? [binding(["x"], "detach from parent")] | |
| 263 | ? [binding(["x"], "sever from upstream")] | |
| 264 | 264 | : []), |
| 265 | 265 | ...(offered === null |
| 266 | 266 | ? [] |
| @@ -437,7 +437,7 @@ export function aboutScreen( | ||
| 437 | 437 | if (!plan.ok) return ctx.toast("that could not be detached", "danger"); |
| 438 | 438 | ctx.push( |
| 439 | 439 | confirmScreen(ctx, screen, { |
| 440 | title: "Detach from parent", | |
| 440 | title: "Sever from upstream", | |
| 441 | 441 | body: [detachPlanWords(plan.value)], |
| 442 | 442 | actions: [{ label: "Detach" }, { label: "Cancel" }], |
| 443 | 443 | onChoose: (i) => { |
src/web/pages/detach.ts +3 −3
| @@ -1,5 +1,5 @@ | ||
| 1 | 1 | /** |
| 2 | * Settings › Danger zone › "Detach from parent" (#7452). The section is the | |
| 2 | * Settings › Danger zone › "Sever from upstream" (#7452). The section is the | |
| 3 | 3 | * plan — what the detach copies and what it ends — and its button starts |
| 4 | 4 | * it. While the repack runs the section says so and since when; a failure |
| 5 | 5 | * 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 { | ||
| 70 | 70 | It is recorded in this repository's history. ${DETACH_AGAIN} |
| 71 | 71 | </p> |
| 72 | 72 | <div class="form-actions"> |
| 73 | ${confirmAction({ action, verb: "Detach from parent" })} | |
| 73 | ${confirmAction({ action, verb: "Sever from upstream" })} | |
| 74 | 74 | </div>`; |
| 75 | 75 | return html`<section class="settings-block" id="detach"> |
| 76 | <h2>Detach from parent</h2> | |
| 76 | <h2>Sever from upstream</h2> | |
| 77 | 77 | ${body} |
| 78 | 78 | </section>`; |
| 79 | 79 | } |
src/web/pages/search.ts +1 −1
| @@ -660,7 +660,7 @@ const DESTRUCTIVE: { | ||
| 660 | 660 | { |
| 661 | 661 | pattern: /^\/([^/]+)\/([^/]+)\/settings\/detach$/, |
| 662 | 662 | describe: (m) => ({ |
| 663 | verb: "Detach from parent", | |
| 663 | verb: "Sever from upstream", | |
| 664 | 664 | title: `Detach ${m[1]}/${m[2]} from its parent?`, |
| 665 | 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 | 666 | phrase: "", |
test/confirm-detach.test.ts +2 −2
| @@ -1,5 +1,5 @@ | ||
| 1 | 1 | /** |
| 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 | |
| 3 | 3 | * it to /-/confirm, which names the fork and posts the detach on the second |
| 4 | 4 | * step exactly as the button used to. |
| 5 | 5 | */ |
| @@ -64,7 +64,7 @@ afterAll(async () => { | ||
| 64 | 64 | await rm(dataDir, { recursive: true, force: true }); |
| 65 | 65 | }); |
| 66 | 66 | |
| 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 () => { | |
| 68 | 68 | const base = `/${fork.ownerName}/${fork.name}`; |
| 69 | 69 | const to = `${base}/settings/detach`; |
| 70 | 70 | 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 | ||
| 75 | 75 | test("the danger zone is two settings-blocks under h2s, no card", async () => { |
| 76 | 76 | const m = main(await (await danger(forker)).text()); |
| 77 | 77 | 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>/); | |
| 79 | 79 | expect(m).toMatch(/<section class="settings-block" id="delete">\s*<h2>Delete this repository<\/h2>/); |
| 80 | 80 | // what goes and what survives |
| 81 | 81 | 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", () => { | ||
| 198 | 198 | expect(home).toContain(`href="${base}/settings/danger#detach"`); |
| 199 | 199 | const danger = await (await fetch(`${servers.url}${base}/settings/danger`, { headers: { cookie } })).text(); |
| 200 | 200 | expect(danger).toContain(`href="/-/confirm?to=${encodeURIComponent(`${base}/settings/detach`)}"`); |
| 201 | expect(danger).toContain("Detach from parent"); | |
| 201 | expect(danger).toContain("Sever from upstream"); | |
| 202 | 202 | |
| 203 | 203 | const post = (origin: string) => |
| 204 | 204 | 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 | ||
| 96 | 96 | expect(attached.nodes.find((n) => n.repo === "alice/root")!.word).toBe(""); |
| 97 | 97 | expect(detachPlanWords({ parent: "alice/root", borrows: false, dryRun: true })).toContain(DETACH_AGAIN); |
| 98 | 98 | }); |
| 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 | ||
| 130 | 130 | |
| 131 | 131 | c.press("x"); |
| 132 | 132 | 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"); | |
| 134 | 134 | c.pushed[1]!.key!({ key: "enter" } as never); |
| 135 | 135 | // The repack may land between two polls, so wait for the outcome, not |
| 136 | 136 | // for the job to be seen running (the next test reads the running row). |
new above
offline
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.