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

Offering a change upstream gives the offerer a receipt page: what was sent, to whom, and its state #14176

opened this

Check · Review · Land · Live — Pushed since the last review. Next: reviewer, pushed since the last review.

Ready to land

torque/forge:torque/14156-offering-a-change-upstream-gives-the-off → main 9 commits fork 8 threads · 8 unresolved

Review

Sign in to review this change.
20 files changed +539 −14
docs/MCP.md +1 −1
@@ -128,7 +128,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
128128 | `forge_proposals` | — | What this forge proposed to its parent; `reachable` false if it is silent | 245 |
129129 | `forge_view` | — | The forge as one picture: counts, apps, runs with stations, health | 282 |
130130 | `forges` | `refused`, `clients` | Forges sent from here (admin), clients, a forge's plan or size | 630 |
131 | `fork` | — | Fork a repository into your account; for a guest, a copy to send changes back from | 232 |
131 | `fork` | `offer`, `receipt` | Fork a repository into your account; `action` offer sends a fork's commit upstream, receipt reads it | 339 |
132132 | `fork_tree` | — | The fork tree around a repo: ancestors, siblings and descendants you may read | 440 |
133133 | `forks` | `chain` | A repo's forks you may see, paged by limit and cursor (next_cursor), each with commits ahead and behind | 480 |
134134 | `front_page` | — | The stranger's front page; admin sets `pinned`/`hidden`/`weights` | 457 |
docs/features/offer-commit-upstream.md +34 −1
@@ -7,7 +7,7 @@ A fork's writer can send a single commit of the fork to its parent as a pull.
77 Open a commit on your fork (`/<you>/<fork>/commit/<oid>`) and press **Offer upstream**. The
88 button shows only to someone who can write to a fork. The forge cuts the branch `offer/<first 12
99 hex of the commit>` in the fork at that commit, opens a pull on the parent from it, and sends you
10 to the pull. The pull's title is the commit's subject; its body names the fork and the commit and
10 to the offer's receipt (below). The pull's title is the commit's subject; its body names the fork and the commit and
1111 says what the fork's check made of it: passed, failed, still running, superseded, or none ran.
1212
1313 The form works without JavaScript. The address must carry the full commit id: anything else
@@ -19,6 +19,39 @@ Open the commit in the history screen (`enter` on a log row) of a fork and press
1919 names the pull (`owner/name#N`) or says why not. The pull opens through the same action as the
2020 page, so anyone watching the parent's pulls on the web sees it appear.
2121
22 The palette's **Offers upstream** (any signed-in person) lists the receipts of what you offered
23 from your forks, newest first, in the page's words: the state, the reason of a decline, the
24 upstream, the fork, the commit and the day. `j`/`k` scroll, `esc` goes back. The screen is
25 `src/tui/screens/offers.ts`; it reads each receipt through `readForkOffer`, as the page does.
26
27 ## The receipt
28
29 Each offer gets a receipt at `/offers/<id>` (#14156): what was sent (the commit and its pull
30 title), to whom (the upstream) and where it stands, in four plain states read from the pull,
31 never stored.
32
33 | State | Meaning |
34 | --- | --- |
35 | sent | Nobody upstream has answered it yet. |
36 | seen | Someone who can write upstream has reviewed or commented on it. |
37 | taken | The upstream merged it. |
38 | declined | The upstream closed it without merging; the reason is the last comment an upstream writer left on it, when they left one. |
39
40 Only someone who can write to the upstream speaks for it: a stranger's comment on a public
41 upstream changes neither the state nor the reason.
42
43 Only the offerer and people who can write to the upstream read it; anyone else, and an id never
44 given, answers 404. The id is 128 random bits, never a pull number. The words are
45 `FORK_OFFER_WORDS` in `src/core/fork_offer.ts`, the same on the page, in the terminal and over
46 MCP.
47
48 ## Over MCP
49
50 `fork` with `action: "offer"`, `repo` (your fork) and a full `commit` id offers it and returns the
51 receipt; `action: "receipt"` with `receipt` reads it again.
52
53 An outsider's offer to a public repository keeps its own receipt (`offer.md`).
54
2255 ## Refusals, in words
2356
2457 `OFFER_COMMIT_WORDS` in `src/actions/offer_commit.ts` says each: not signed in, cannot write to
src/actions/offer_commit.ts +4 −1
@@ -9,6 +9,7 @@
99
1010 import type { App } from "../app.ts";
1111 import type { CommitCheck } from "../checks/commit_check.ts";
12 import { recordForkOffer } from "../core/fork_offer.ts";
1213 import { openPullFromHead, type Pull } from "../core/pulls.ts";
1314 import { canRead, getRepoById, type Repo } from "../core/repos.ts";
1415 import type { User } from "../core/users.ts";
@@ -62,6 +63,8 @@ export function verdictWords(check: CommitCheck | null): string {
6263 export interface CommitOffered {
6364 readonly pull: Pull;
6465 readonly parent: Repo;
66 /** The id of the offerer's receipt page, `/offers/<receipt>` (#14156). */
67 readonly receipt: string;
6568 }
6669
6770 /** The branch an offered commit travels on: named for the commit, cut in the fork. */
@@ -110,5 +113,5 @@ export async function offerCommit(
110113 if (cut.ok) await deleteBranch(app, writer.value, fork, branch);
111114 return err("not_opened");
112115 }
113 return ok({ pull: opened.value, parent });
116 return ok({ pull: opened.value, parent, receipt: recordForkOffer(app.db, opened.value.id, writer.value.id) });
114117 }
src/core/fork_offer.ts added +124
@@ -0,0 +1,124 @@
1 /**
2 * The receipt of a fork's offer upstream (#14156): what was sent (the pull's commits), to whom
3 * (the upstream) and where it stands, in four plain states read from the pull, never stored.
4 * Only the offerer and the upstream's writers may read one; anyone else gets undefined, the
5 * same as an id never given.
6 */
7 import type { Database } from "bun:sqlite";
8 import { getIssueById, listComments } from "./issues.ts";
9 import { getPull } from "./pulls.ts";
10 import { canWrite, getRepoById, type Repo } from "./repos.ts";
11 import { listReviews } from "./reviews.ts";
12 import { getUserById, type User } from "./users.ts";
13
14 export type ForkOfferState = "sent" | "seen" | "taken" | "declined";
15
16 /** The words said once for each state, for the page, the MCP and the terminal alike. */
17 export const FORK_OFFER_WORDS: Readonly<Record<ForkOfferState, string>> = {
18 sent: "Sent. Nobody upstream has answered it yet.",
19 seen: "Seen. Someone who can write upstream has reviewed or commented on it.",
20 taken: "Taken. The upstream merged it.",
21 declined: "Declined. The upstream closed it without merging.",
22 };
23
24 export interface ForkOfferReceipt {
25 readonly receipt: string;
26 readonly state: ForkOfferState;
27 readonly words: string;
28 /** Why it was declined, when someone upstream said so; null otherwise. */
29 readonly reason: string | null;
30 readonly upstream: string;
31 readonly fork: string;
32 readonly pull: number;
33 readonly title: string;
34 readonly commits: readonly string[];
35 readonly offeredAt: string;
36 }
37
38 const newId = (): string => crypto.randomUUID().replace(/-/g, "");
39 const ID = /^[0-9a-f]{32}$/;
40
41 /** Keep a receipt for the pull `issueId` offered by `offererId`; returns its id. */
42 export function recordForkOffer(db: Database, issueId: string, offererId: string): string {
43 const id = newId();
44 db.query("INSERT INTO fork_offer (id, issue_id, offerer_id, created_at) VALUES (?1, ?2, ?3, ?4)").run(
45 id,
46 issueId,
47 offererId,
48 new Date().toISOString(),
49 );
50 return id;
51 }
52
53 const repoName = (r: Repo): string => `${r.ownerName}/${r.name}`;
54
55 /**
56 * The receipt's state now. `commits` are the short ids the offer branch is named for; the
57 * pull itself holds the rest. `viewer` must be the offerer or write to the upstream.
58 */
59 export function readForkOffer(db: Database, viewer: User | undefined, id: string): ForkOfferReceipt | undefined {
60 if (viewer === undefined || !ID.test(id)) return undefined;
61 const row = db
62 .query<{ issue_id: string; offerer_id: string; created_at: string }, [string]>(
63 "SELECT issue_id, offerer_id, created_at FROM fork_offer WHERE id = ?1",
64 )
65 .get(id);
66 if (row === null) return undefined;
67 const issue = getIssueById(db, row.issue_id);
68 const upstream = issue === undefined ? undefined : getRepoById(db, issue.repoId);
69 const pull = issue === undefined ? undefined : getPull(db, issue.repoId, issue.number);
70 if (issue === undefined || upstream === undefined || pull === undefined) return undefined;
71 if (viewer.id !== row.offerer_id && !canWrite(db, upstream, viewer)) return undefined;

'seen' is set by any non-offerer comment, including a stranger on a public upstream; the receipt says 'Someone upstream'. Count only reviews and comments by people who can write to the upstream (canWrite), and test that an outsider's comment leaves the state at sent.

72 const fork = getRepoById(db, pull.headRepoId);
73 // Only someone who can write to the upstream speaks for it: a stranger's comment on a public
74 // upstream is neither an answer nor a reason.
75 const voices = new Map<string, boolean>();
76 const speaksUpstream = (authorId: string): boolean => {
outdated

The decline reason is the last comment by anyone but the offerer, so an outsider's comment is shown as the upstream's reason, and the ?? null) || null is hard to read. Restrict to upstream writers (or the closer) and write it as a plain find/map. Tested only with a writer's comment today.

77 if (authorId === row.offerer_id) return false;
78 let yes = voices.get(authorId);
79 if (yes === undefined) {
80 const who = getUserById(db, authorId);
81 yes = who !== undefined && canWrite(db, upstream, who);
82 voices.set(authorId, yes);
83 }
84 return yes;
85 };
86 const said = listComments(db, issue.id, { kind: "comment" }).filter((c) => speaksUpstream(c.authorId));
87 const answered = said.length > 0 || listReviews(db, pull.id).some((r) => speaksUpstream(r.authorId));
88 const state: ForkOfferState =
89 pull.mergedAt !== null ? "taken" : pull.state === "closed" ? "declined" : answered ? "seen" : "sent";
90 const reasonText = state === "declined" ? (said.at(-1)?.body.trim() ?? "") : "";
91 const reason = reasonText === "" ? null : reasonText;
92 return {
93 receipt: id,
94 state,
95 words: FORK_OFFER_WORDS[state],
96 reason,
97 upstream: repoName(upstream),
98 fork: fork === undefined ? "" : repoName(fork),
99 pull: pull.number,
100 title: pull.title,
101 commits: [pull.headBranch.replace(/^offer\//, "")],
102 offeredAt: row.created_at,
103 };
104 }
105
106 /** `Nov 16, 2026`, in UTC, from an ISO time: the date the page and the terminal both print. */
107 export function offerDay(iso: string): string {
108 const d = new Date(iso);
109 const month = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][d.getUTCMonth()];
110 return `${month} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
111 }
112
113 /**
114 * The receipts `viewer` holds as an offerer, newest first, at most `limit` (20 by default), each
115 * read through `readForkOffer`: the terminal's Offers upstream screen.
116 */
117 export function listForkOffers(db: Database, viewer: User, limit = 20): ForkOfferReceipt[] {
118 return db
119 .query<{ id: string }, [string, number]>(
120 "SELECT id FROM fork_offer WHERE offerer_id = ?1 ORDER BY created_at DESC, id DESC LIMIT ?2",
121 )
122 .all(viewer.id, Math.max(1, Math.min(100, Math.floor(limit))))
123 .flatMap((r) => readForkOffer(db, viewer, r.id) ?? []);
124 }
src/core/migration-pins/20261116120000-fork-offer.pin added +1
@@ -0,0 +1,1 @@
1 17f33ae261fab8e3338574c377b609949e8ed395a9648f5b3b610dc62ab7e4f1
src/core/migrations/20261116120000-fork-offer.ts added +11
@@ -0,0 +1,11 @@
1 // A fork's offer upstream is given a receipt page (#14156): a random id, the pull it opened on the
2 // upstream and who offered. New table only; the pull is the repository's own and stays the truth.
3 export default `
4 CREATE TABLE fork_offer (
5 id TEXT PRIMARY KEY,
6 issue_id TEXT NOT NULL REFERENCES issue(id) ON DELETE CASCADE,
7 offerer_id TEXT NOT NULL REFERENCES user(id) ON DELETE CASCADE,
8 created_at TEXT NOT NULL
9 );
10 CREATE INDEX fork_offer_offerer ON fork_offer (offerer_id, created_at);
11 `;
src/core/reserved.ts +1
@@ -111,6 +111,7 @@ export const SYSTEM_NAMES: readonly string[] = [
111111 "og",
112112 "organizations",
113113 "now",
114 "offers",
114115 "resilience",
115116 "maintenance",
116117 "origins",
src/http/mcp/tools/fork.ts +31 −4
@@ -3,20 +3,47 @@ import { VERIFY_FIRST } from "../../../actions/verify_words.ts";
33 import { GUEST_REFUSALS, isGuestRefusal } from "../../../core/contribute.ts";
44 import { NOT_A_MEMBER } from "../../../core/roles.ts";
55 import { storageLimitMessage } from "../../../core/storage.ts";
6 import { offerCommit, OFFER_COMMIT_WORDS } from "../../../actions/offer_commit.ts";
7 import { readForkOffer } from "../../../core/fork_offer.ts";
8 import { isSafeOid } from "../../../git/guard.ts";
9 import { resolveOid } from "../../../git/merge.ts";
10 import { commitLog } from "../../../git/read.ts";
11 import { repoDir } from "../../../git/repos.ts";
612 import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
713
814 /** The MCP door to `POST /api/v1/repos/:owner/:name/forks`: the same action, the same refusals. */
915 export const tool: Tool = {
1016 name: "fork",
11 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",
12 description: "Fork a repository into your account; for a guest, a copy to send changes back from.",
17 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, says, reason, upstream, url }`; `{ action: \"receipt\", receipt }` reads it again (offerer and upstream writers only; the page is `/offers/<receipt>`)",
18 description: "Fork a repository into your account; `action` offer sends a fork's commit upstream, receipt reads it.",
1319 inputSchema: {
1420 type: "object",
15 properties: { repo: REPO_ARG, name: { type: "string" } },
16 required: ["repo"],
21 properties: {
22 repo: REPO_ARG,
23 name: { type: "string" },
24 action: { type: "string", enum: ["offer", "receipt"] },
25 commit: { type: "string", maxLength: 40 },
26 receipt: { type: "string", maxLength: 32 },
27 },
1728 },
1829 writes: true,
1930 async run(ctx, user, args) {
31 if (args["action"] === "receipt") {
32 const got = readForkOffer(ctx.app.db, user, str(args["receipt"]));
33 return got === undefined ? bad("not_found", "no such receipt for you") : good({ ...got, says: got.words });
34 }
35 if (args["action"] === "offer") {
36 const fork = repoArg(ctx, user, args);
37 if (isAnswer(fork)) return fork;
38 const dir = repoDir(ctx.app.reposRoot, fork.ownerName, fork.name);
39 const oid = isSafeOid(str(args["commit"])) ? await resolveOid(dir, str(args["commit"])) : undefined;
40 if (oid === undefined) return bad("no_such_commit", OFFER_COMMIT_WORDS.no_such_commit);
41 const log = await commitLog(dir, oid, { limit: 1 });
42 const made = await offerCommit(ctx.app, user, fork, oid, log.ok ? (log.value[0]?.subject ?? "") : "");
43 if (!made.ok) return bad(made.error, OFFER_COMMIT_WORDS[made.error]);
44 const got = readForkOffer(ctx.app.db, user, made.value.receipt);
45 return good({ ...got, says: got?.words, url: `${ctx.url.origin}/offers/${made.value.receipt}` });
46 }
2047 const parent = repoArg(ctx, user, args);
2148 if (isAnswer(parent)) return parent;
2249 const forked = await forkRepo(ctx.app, user, parent, str(args["name"]) || undefined);
src/http/route_marks.ts +1
@@ -155,6 +155,7 @@ export const HEADS: Readonly<Record<string, Mark | "mixed">> = {
155155 "/notes": "open",
156156 "/now": "open",
157157 "/oauth": "open",
158 "/offers": "open",
158159 "/og": "open",
159160 "/openapi.json": "open",
160161 "/opensearch.xml": "open",
src/http/server.ts +2
@@ -248,6 +248,7 @@ import {
248248 branchesPage,
249249 } from "../web/pages/branches.ts";
250250 import { offerCommitPost } from "../web/pages/offer-upstream.ts";
251 import { offerReceiptPage } from "../web/pages/offer-receipt.ts";
251252 import { iterationsPage, noteSubmit } from "../web/pages/iterations.ts";
252253 import { mainSubmit, registerSubmit, retireSubmit, valuesSubmit, variantBoardPage } from "../web/pages/app_variants.ts";
253254 import { buildsPage, deletePinSubmit, newBuildPage, pinBuildSubmit, previewBuildSubmit } from "../web/pages/builds.ts";
@@ -1134,6 +1135,7 @@ export function buildRouter(): Router<Handler> {
11341135 router.add("GET", "/system", systemPage);
11351136 router.add("GET", "/system/stream", systemStream);
11361137 router.add("GET", "/system/bottleneck", bottleneckPage);
1138 router.add("GET", "/offers/:id", offerReceiptPage);
11371139 router.add("GET", "/contribute", contributePage);
11381140 // The one path a change follows, in four words (#7703); literal, above /:owner.
11391141 router.add("GET", "/pipeline", pipelinePage);
src/tui/screens/entries.ts +2
@@ -72,6 +72,7 @@ import { entry as footing } from "./footing.ts";
7272 import { entry as maintenanceWeek } from "./maintenanceweek.ts";
7373 import { entry as offsite } from "./offsite.ts";
7474 import { entry as waiting } from "./waiting.ts";
75 import { entry as offers } from "./offers.ts";
7576 import { entry as waitingForMe } from "./waiting_for_me.ts";
7677 import { entry as tellUndo } from "./tell_undo.ts";
7778 import { entry as slowPagesEntry } from "./slowpages.ts";
@@ -151,6 +152,7 @@ export const ENTRIES: readonly PaletteEntry[] = [
151152 offsite,
152153 waiting,
153154 waitingForMe,
155 offers,
154156 tellUndo,
155157 slowPagesEntry,
156158 telemetry,
src/tui/screens/offers.ts added +63
@@ -0,0 +1,63 @@
1 /**
2 * Offers upstream, from the palette: the receipts of the offers the signed-in person made from
3 * their forks (#14156), read through `listForkOffers`/`readForkOffer`, so the gate (the offerer
4 * or an upstream writer) and the words (`FORK_OFFER_WORDS`) are the page's at `/offers/<id>`.
5 * Read-only.
6 */
7
8 import { offerDay, listForkOffers, type ForkOfferReceipt } from "../../core/fork_offer.ts";
9 import type { Ctx, Screen } from "../app/app.ts";
10 import { binding } from "../app/keys.ts";
11 import type { Session } from "../session.ts";
12 import { style } from "../term/style.ts";
13 import { Scroll, drawLines, hitScroll } from "./common.ts";
14 import type { PaletteEntry } from "./entries.ts";
15
16 const mayRead = (session: Session): boolean => session.user !== undefined && session.user.kind !== "agent";
17
18 /**
19 * One receipt as text lines, the page's rows in the page's words; detail lines start with a space.
20 */
21 export function offerLines(r: ForkOfferReceipt): string[] {
22 return [
23 `${r.upstream}#${String(r.pull)} ${r.title}`,
24 ` ${r.words}`,
25 ...(r.reason === null ? [] : [` Reason given: ${r.reason}`]),
26 ` Sent to ${r.upstream} from ${r.fork}: ${r.commits.join(" ")} on ${offerDay(r.offeredAt)}`,
27 ];
28 }
29
30 export function offersScreen(ctx: Ctx, receipts: readonly ForkOfferReceipt[]): Screen {
31 const scroll = new Scroll();
32 const lines = receipts.length === 0 ? ["You have offered nothing upstream."] : receipts.flatMap(offerLines);
33 return {
34 title: "Offers upstream",
35 keys: [binding(["j", "k"], "scroll"), binding(["esc", "q"], "back")],
36 render(area, s) {
37 const c = ctx.theme.c;
38 const spans = lines.map((text) => [{ text, style: style(text.startsWith(" ") || receipts.length === 0 ? c.mutedFg : c.fg, c.bg) }]);
39 drawLines(s, area, c, scroll, spans);
40 hitScroll(ctx, area, scroll, lines.length);
41 },
42 key(e) {
43 if (scroll.key(e, lines.length)) return true;
44 if (e.key === "esc" || e.key === "q") {
45 ctx.pop();
46 return true;
47 }
48 return false;
49 },
50 };
51 }
52
53 export const entry: PaletteEntry = {
54 id: "offers-upstream",
55 title: "Offers upstream",
56 hint: "the receipts of what you offered from your forks",
57 after: ["waiting-for-me"],
58 offered: mayRead,
59 run: (session, ctx) => {
60 if (session.user === undefined) return;
61 ctx.push(offersScreen(ctx, listForkOffers(session.app.db, session.user)));
62 },
63 };
src/web/pages/offer-receipt.ts added +32
@@ -0,0 +1,32 @@
1 /**
2 * /offers/<id>: the receipt of a fork's offer upstream (#14156) — the commit sent, to whom and
3 * where it stands, in the words the MCP `offer` tool returns (`core/fork_offer.ts`). Only the
4 * offerer and the upstream's writers read it; anyone else sees the page of an id never given.
5 */
6 import { offerDay, readForkOffer } from "../../core/fork_offer.ts";
7 import { getRepo } from "../../core/repos.ts";
8 import type { Ctx } from "../../http/context.ts";
9 import { notFoundPage, pageHead, repoBase, signInFirst } from "../chrome.ts";
10 import { html } from "../html.ts";
11 import { page } from "../layout.ts";
12
13 export function offerReceiptPage(ctx: Ctx): Response {
14 if (!ctx.auth.user) return signInFirst(ctx);

Both doors: this page has no terminal twin. Add a src/tui/ screen that shows the same receipt through readForkOffer and FORK_OFFER_WORDS, with its entry per AGENTS.md.

15 const r = readForkOffer(ctx.app.db, ctx.auth.user, ctx.params.id ?? "");
16 if (r === undefined) return notFoundPage(ctx);
17 const [owner = "", name = ""] = r.upstream.split("/");
18 const upstream = getRepo(ctx.app.db, owner, name);
19 const pullHref = upstream === undefined ? null : `${repoBase(upstream)}/pulls/${r.pull}`;
20 const body = html`${pageHead("Offer receipt")}
21 <p id="offer-state">${r.words}</p>
outdated

Principle 1/7: the state is said twice (badge and sentence) and the facts under it repeat the page title. Drop the badge, keep the one sentence, and keep the dl as the only list.

22 ${r.reason === null ? html`` : html`<p id="offer-reason"><strong>Reason given:</strong> ${r.reason}</p>`}
23 <dl class="status-rows">
24 <div><dt>Sent to</dt><dd>${r.upstream}</dd></div>
25 <div><dt>From</dt><dd>${r.fork}</dd></div>
26 <div><dt>Commit</dt><dd>${r.commits.map((c) => html`<code>${c}</code> `)}${pullHref === null ? r.title : html`<a href="${pullHref}">${r.title}</a>`}</dd></div>
27 <div><dt>Sent on</dt><dd>${offerDay(r.offeredAt)}</dd></div>
28 </dl>`;
outdated

Principle 8 (plain words): 'Sent at' prints a raw ISO timestamp. Use the date format the other pages use. Also, 'Commits' shows only the offer branch's short id, not the commits sent; show the commit subject/id as the issue's box 1 asks.

29 const response = page({ ctx, title: "Offer receipt", body });
30 response.headers.set("cache-control", "no-store");
31 return response;
32 }
src/web/pages/offer-upstream.ts +1 −1
@@ -74,7 +74,7 @@ export async function offerCommitPost(ctx: Ctx): Promise<Response> {
7474 const offered = await offerCommit(ctx.app, ctx.auth.user, repo, commit.oid, commit.subject);
7575 if (!offered.ok)
7676 return flashTo(ctx, back, { tone: "danger", message: OFFER_COMMIT_WORDS[offered.error] });
77 return flashTo(ctx, `${repoBase(offered.value.parent)}/pulls/${offered.value.pull.number}`, {
77 return flashTo(ctx, `/offers/${offered.value.receipt}`, {
7878 message: `Offered upstream as #${offered.value.pull.number}.`,
7979 });
8080 }
test/fork-offer-receipt.test.ts added +219
@@ -0,0 +1,219 @@
1 /**
2 * A fork's offer upstream gives its offerer a receipt page, /offers/<id>, and the same receipt
3 * through the MCP `fork` tool and the terminal's Offers upstream screen (#14156): one test for
4 * each state, the reason of a decline, and who may read it.
5 */
6 import { afterAll, beforeAll, 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 { offerCommit } from "../src/actions/offer_commit.ts";
11 import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
12 import { setRole } from "../src/actions/roles.ts";
13 import { createApp, type App } from "../src/app.ts";
14 import { FORK_OFFER_WORDS, listForkOffers, offerDay, readForkOffer, type ForkOfferState } from "../src/core/fork_offer.ts";
15 import { addComment, setIssueState } from "../src/core/issues.ts";
16 import { getRepo, type Repo } from "../src/core/repos.ts";
17 import { submitReview } from "../src/core/reviews.ts";
18 import { createToken } from "../src/core/tokens.ts";
19 import { createUser, type User } from "../src/core/users.ts";
20 import { serve, type Servers } from "../src/http/server.ts";
21 import type { Ctx } from "../src/tui/app/app.ts";
22 import { entry as offersEntry, offerLines } from "../src/tui/screens/offers.ts";
23 import type { Session } from "../src/tui/session.ts";
24 import { theme } from "../src/tui/ui/theme.ts";
25 import { quietLogs } from "./helpers/globals.ts";
26
27 quietLogs();
28
29 let dataDir: string;
30 let app: App;
31 let servers: Servers;
32 let users: User[] = [];
33 let n = 0;
34
35 const mk = async (username: string, first = false): Promise<User> => {
36 const made = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: "a-good-passphrase", adminIfFirst: first });
37 if (!made.ok) throw new Error(made.error);
38 return made.value;
39 };
40 const forkOf = (): Repo => getRepo(app.db, "ravi", "yard")!;
41 const signIn = async (username: string): Promise<string> => {
42 const r = await fetch(`${servers.url}/signin`, { method: "POST", body: new URLSearchParams({ username, password: "a-good-passphrase" }), redirect: "manual" });
43 return (r.headers.get("set-cookie") ?? "").split(";")[0]!;
44 };
45 const offered = async () => {
46 const c = await commitToBranch(app, users[2]!, forkOf(), { message: `mine ${n}`, files: [{ path: `f${n++}.txt`, content: "x\n" }] });
47 if (!c.ok) throw new Error(String(c.error));
48 const made = await offerCommit(app, users[2]!, forkOf(), c.value.commitOid, `mine ${n}`);
49 if (!made.ok) throw new Error(made.error);
50 return made.value;
51 };
52 const read = (id: string, who = users[2]!) => readForkOffer(app.db, who, id)!;
53
54 beforeAll(async () => {
55 dataDir = await mkdtemp(join(tmpdir(), "forge-fork-offer-receipt-"));
56 app = createApp({ dataDir, port: 0, host: "forge.test" });
57 servers = await serve(app);
58 users = [await mk("hank", true), await mk("olive"), await mk("ravi"), await mk("zed")];
59 for (const name of ["olive", "ravi", "zed"]) setRole(app, users[0]!, name, "member");
60 const r = await createRepo(app, users[1]!, { name: "yard", visibility: "public" });
61 if (!r.ok) throw new Error(String(r.error));
62 await commitToBranch(app, users[1]!, r.value, { message: "first", files: [{ path: "a.txt", content: "a\n" }] });
63 const f = await forkRepo(app, users[2]!, r.value);
64 if (!f.ok) throw new Error(String(f.error));
65 }, 30_000);
66
67 afterAll(async () => {
68 await servers.stop();
69 await rm(dataDir, { recursive: true, force: true });
70 });
71
72 test("a receipt exists for each state, in its own words", async () => {
73 const seen: Record<ForkOfferState, string> = { sent: "", seen: "", taken: "", declined: "" };
74
75 const sent = await offered();
76 expect(read(sent.receipt).state).toBe("sent");
77 seen.sent = read(sent.receipt).words;
78
79 const reviewed = await offered();
80 submitReview(app.db, { issueId: reviewed.pull.id, authorId: users[1]!.id, state: "commented", commitOid: reviewed.pull.headOid });
81 expect(read(reviewed.receipt).state).toBe("seen");
82 seen.seen = read(reviewed.receipt).words;
83
84 const commented = await offered();
85 addComment(app.db, { issueId: commented.pull.id, authorId: users[2]!.id, body: "my own note" });
86 expect(read(commented.receipt).state).toBe("sent");
87 addComment(app.db, { issueId: commented.pull.id, authorId: users[1]!.id, body: "looking" });
88 expect(read(commented.receipt).state).toBe("seen");
89
90 const taken = await offered();
91 app.db.query("UPDATE pull SET merged_at = ?2 WHERE issue_id = ?1").run(taken.pull.id, new Date().toISOString());
92 setIssueState(app.db, taken.pull.id, "closed");
93 expect(read(taken.receipt).state).toBe("taken");
94 seen.taken = read(taken.receipt).words;
95
96 const declined = await offered();
97 setIssueState(app.db, declined.pull.id, "closed", "dropped");
98 const d = read(declined.receipt);
99 expect(d.state).toBe("declined");
100 expect(d.reason).toBeNull();
101 seen.declined = d.words;
102
103 expect(seen).toEqual(FORK_OFFER_WORDS);
104 expect(new Set(Object.values(seen)).size).toBe(4);
105 });
106
107 test("a declined offer shows the reason when one was given", async () => {
108 const o = await offered();
109 addComment(app.db, { issueId: o.pull.id, authorId: users[1]!.id, body: "We take this through the plugin API instead." });
110 setIssueState(app.db, o.pull.id, "closed", "dropped");
111 const r = read(o.receipt);
112 expect(r.reason).toBe("We take this through the plugin API instead.");
113 const page = await (await fetch(`${servers.url}/offers/${o.receipt}`, { headers: { cookie: await signIn("ravi") } })).text();
114 expect(page).toContain("Declined.");
115 expect(page).toContain("We take this through the plugin API instead.");
116 });
117
118 test("a stranger's comment is neither an answer nor a reason; only an upstream writer speaks", async () => {
119 const o = await offered();
120 addComment(app.db, { issueId: o.pull.id, authorId: users[3]!.id, body: "drive-by from zed" });
121 submitReview(app.db, { issueId: o.pull.id, authorId: users[3]!.id, state: "commented", commitOid: o.pull.headOid });
122 expect(read(o.receipt).state).toBe("sent");
123 setIssueState(app.db, o.pull.id, "closed", "dropped");
124 const r = read(o.receipt);
125 expect(r.state).toBe("declined");
126 expect(r.reason).toBeNull();
127 addComment(app.db, { issueId: o.pull.id, authorId: users[1]!.id, body: "owner says no" });
128 addComment(app.db, { issueId: o.pull.id, authorId: users[3]!.id, body: "zed again" });
129 expect(read(o.receipt).reason).toBe("owner says no");
130 });
131
132 test("the receipt page shows the day, not the timestamp", async () => {
133 const o = await offered();
134 const mine = [read(o.receipt)];
135 expect(offerDay("2026-11-16T23:59:59.000Z")).toBe("Nov 16, 2026");
136 const page = await (await fetch(`${servers.url}/offers/${o.receipt}`, { headers: { cookie: await signIn("ravi") } })).text();
137 expect(page).toContain(offerDay(mine[0]!.offeredAt));
138 expect(page).not.toContain(mine[0]!.offeredAt);
139 expect(page).not.toContain('class="badge"');
140 });
141
142 test("the page names what was sent, to whom, and escapes what others wrote", async () => {
143 const o = await offered();
144 addComment(app.db, { issueId: o.pull.id, authorId: users[1]!.id, body: "<script>alert(1)</script>" });
145 setIssueState(app.db, o.pull.id, "closed", "dropped");
146 const res = await fetch(`${servers.url}/offers/${o.receipt}`, { headers: { cookie: await signIn("ravi") } });
147 const page = await res.text();
148 expect(res.status).toBe(200);
149 expect(page).toContain("olive/yard");
150 expect(page).toContain("ravi/yard");
151 expect(page).toContain(o.pull.headBranch.replace("offer/", ""));
152 expect(page).not.toContain("<script>alert(1)</script>");
153 expect(page).toContain("&lt;script&gt;");
154 });
155
156 test("only the offerer and the upstream's writers read a receipt", async () => {
157 const o = await offered();
158 const path = `${servers.url}/offers/${o.receipt}`;
159 expect((await fetch(path, { headers: { cookie: await signIn("ravi") } })).status).toBe(200);
160 expect((await fetch(path, { headers: { cookie: await signIn("olive") } })).status).toBe(200);
161 expect((await fetch(path, { headers: { cookie: await signIn("zed") } })).status).toBe(404);
162 expect((await fetch(path, { redirect: "manual" })).status).toBe(303);
163 expect((await fetch(`${servers.url}/offers/${"0".repeat(32)}`, { headers: { cookie: await signIn("ravi") } })).status).toBe(404);
164 expect((await fetch(`${servers.url}/offers/x%27%20OR%201=1`, { headers: { cookie: await signIn("ravi") } })).status).toBe(404);
165 expect(readForkOffer(app.db, users[3]!, o.receipt)).toBeUndefined();
166 });
167
168 test("the MCP fork tool offers a commit and returns the same receipt", async () => {
169 const c = await commitToBranch(app, users[2]!, forkOf(), { message: "via mcp", files: [{ path: "mcp.txt", content: "x\n" }] });
170 if (!c.ok) throw new Error(String(c.error));
171 const token = createToken(app.db, users[2]!.id, "rw", "rw").token;
172 const call = async (args: unknown, tok = token) => {
173 const res = await fetch(`${servers.url}/mcp`, {
174 method: "POST",
175 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${tok}` },
176 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "fork", arguments: args } }),
177 });
178 const body = (await res.json()) as any;
179 return body.result;
180 };
181 const made = await call({ repo: "ravi/yard", action: "offer", commit: c.value.commitOid });
182 const got = JSON.parse(made.content[0].text);
183 expect(got.state).toBe("sent");
184 expect(got.says).toBe(FORK_OFFER_WORDS.sent);
185 expect(got.upstream).toBe("olive/yard");
186 expect(got.receipt).toMatch(/^[0-9a-f]{32}$/);
187 const again = JSON.parse((await call({ action: "receipt", receipt: got.receipt })).content[0].text);
188 expect(again.says).toBe(FORK_OFFER_WORDS.sent);
189 const zed = createToken(app.db, users[3]!.id, "rw", "rw").token;
190 expect((await call({ action: "receipt", receipt: got.receipt }, zed)).isError).toBe(true);
191 expect((await call({ repo: "ravi/yard", action: "offer", commit: "--upload-pack=x" })).isError).toBe(true);
192 });
193
194 test("the terminal's Offers upstream lists the offerer's receipts in the page's words, gated as the page is", async () => {
195 const o = await offered();
196 addComment(app.db, { issueId: o.pull.id, authorId: users[1]!.id, body: "not this one" });
197 setIssueState(app.db, o.pull.id, "closed", "dropped");
198 const mine = listForkOffers(app.db, users[2]!);
199 expect(mine[0]!.receipt).toBe(o.receipt); // newest first
200 expect(mine.length).toBeGreaterThan(1);
201 expect(mine[0]).toEqual(read(o.receipt)); // the same read as the page
202 expect(listForkOffers(app.db, users[1]!)).toEqual([]); // the upstream's owner offered nothing
203 expect(listForkOffers(app.db, users[3]!)).toEqual([]);
204 const lines = offerLines(mine[0]!);
205 expect(lines).toEqual([
206 `olive/yard#${o.pull.number} ${o.pull.title}`,
207 ` ${FORK_OFFER_WORDS.declined}`,
208 " Reason given: not this one",
209 ` Sent to olive/yard from ravi/yard: ${o.pull.headBranch.replace("offer/", "")} on ${offerDay(mine[0]!.offeredAt)}`,
210 ]);
211 const session = (user: User | undefined) => ({ user, app }) as unknown as Session;
212 expect(offersEntry.offered(session(users[2]!))).toBe(true);
213 expect(offersEntry.offered(session(undefined))).toBe(false);
214 expect(offersEntry.offered(session({ ...users[2]!, kind: "agent" } as User))).toBe(false);
215 const pushed: Array<{ title: string }> = [];
216 const ctx = { theme: theme("dark"), push: (s: { title: string }) => void pushed.push(s) } as unknown as Ctx;
217 offersEntry.run(session(users[2]!), ctx);
218 expect(pushed.map((s) => s.title)).toEqual(["Offers upstream"]);
219 });
test/no-polling.test.ts +1
@@ -326,6 +326,7 @@ const NOT_WALKED: Record<string, string> = {
326326 "/icons/:spec.png": "an image, not a page",
327327 "/migrate/jobs/:job": "needs a migration job",
328328 "/now/:stage": "the stage word is one the seed cannot guess",
329 "/offers/:id": "needs a fork offer receipt, which the seed has none of",
329330 "/resilience/nightly/:job": "needs a nightly job name",
330331 "/runs/:id": "the seed creates no run",
331332 "/signin/access/:token": "needs a one-time access link an admin minted",
test/offer-commit.test.ts +4 −5
@@ -101,12 +101,11 @@ test("offering a commit opens a pull on the parent naming the fork and its check
101101 const res = await post(`/ravi/yard/commit/${oids[0]}/offer`, await signIn("ravi"));
102102 expect(res.status).toBe(303);
103103 const to = res.headers.get("location") ?? "";
104 expect(to).toMatch(/^\/olive\/yard\/pulls\/\d+/);
105 const number = Number(/pulls\/(\d+)/.exec(to)![1]);
106 const parent = getRepo(app.db, "olive", "yard")!;
104 expect(to).toMatch(/^\/offers\/[0-9a-f]{32}/);
105 const receipt = /^\/offers\/([0-9a-f]{32})/.exec(to)![1]!;
outdated

MAX(number) over all issues is a guess at the pull number and can pick another pull. Read it from the receipt row (fork_offer -> issue -> number).

107106 const issue = app.db
108 .query<{ id: string }, [string, number]>("SELECT id FROM issue WHERE repo_id = ? AND number = ?")
109 .get(parent.id, number)!;
107 .query<{ id: string }, [string]>("SELECT issue_id AS id FROM fork_offer WHERE id = ?")
108 .get(receipt)!;
110109 const pull = getIssueById(app.db, issue.id)!;
111110 expect(pull.title).toBe("mine one");
112111 expect(pull.body).toContain("ravi/yard");
test/pages-budget.test.ts +3
@@ -28,6 +28,7 @@ import { createApp, type App } from "../src/app.ts";
2828 import { createApp as createAppRecord } from "../src/core/apps.ts";
2929 import { startChatBuild } from "../src/core/chat_build.ts";
3030 import { createConversation } from "../src/core/conversations.ts";
31 import { recordForkOffer } from "../src/core/fork_offer.ts";
3132 import { issueReceipt } from "../src/core/offer_receipt.ts";
3233 import { createIssue } from "../src/core/issues.ts";
3334 import { pin } from "../src/core/pins.ts";
@@ -173,6 +174,8 @@ beforeAll(async () => {
173174 app.db.run("INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid) VALUES (?1, 'main', 'topic', '', 'h')", [pull.value.id]);
174175 // An offer's receipt, for `/api/v1/offers/:receipt`: random, so the fixture reads it back.
175176 FIXTURE["/api/v1/offers/:receipt"] = `/api/v1/offers/${issueReceipt(app.db, pull.value.id)}`;
177 // A fork's offer upstream, for its receipt page (#14156): random, so the fixture reads it back.
178 FIXTURE["/offers/:id"] = `/offers/${recordForkOffer(app.db, pull.value.id, bob.id)}`;
176179 // A conversation that builds, with a version on its branch, for the two build reads.
177180 const talk = createConversation(app.db, alice.id);
178181 if (!talk.ok) throw new Error(talk.error);
test/palette-roster.test.ts +3 −1
@@ -130,10 +130,11 @@ test("a site-admin person is offered the whole roster", () => {
130130 ["pulls-to-land", "Pulls to land", "approved pulls, stale crew pulls, unproposed work"],
131131 ["valves", "Valves", "the week's budget as a valve per repository; turn one and the crew obeys"],
132132 ["waiting-for-me", "Waiting for me", "issues and pulls that wait for you"],
133 ["tell-undo", "Take a tell back", "a tell you sent in the last minute, while nobody has read it"],
133 ["offers-upstream", "Offers upstream", "the receipts of what you offered from your forks"],
134134 ["refused-asks", "Refused first asks", "the last 20 first asks turned away"],
135135 ["disks", "Disks", "machines' disk readings: 30-day write rate and projected rated-TBW date"],
136136 ["telemetry", "Telemetry", "which agents may read flow and system; enter flips the grant"],
137 ["tell-undo", "Take a tell back", "a tell you sent in the last minute, while nobody has read it"],
137138 ["bottleneck", "Where the bottleneck is", "what limits the forge, what the host is tuned to, what changed"],
138139 ["health-voice", "Health — spoken", "how the forge is, in two plain sentences"],
139140 ["stalls", "Main-thread stalls", "the last hour's stall ms by route"],
@@ -417,6 +418,7 @@ test("a member person is offered the signed-in roster without the admin entries"
417418 ["bugs", "Bugs", "open bugs and the bug clock"],
418419 ["health-voice", "Health — spoken", "how the forge is, in two plain sentences"],
419420 ["waiting-for-me", "Waiting for me", "issues and pulls that wait for you"],
421 ["offers-upstream", "Offers upstream", "the receipts of what you offered from your forks"],
420422 ["tell-undo", "Take a tell back", "a tell you sent in the last minute, while nobody has read it"],
421423 ["audit", "Who can do what", "each app's doors from its contract.json: yes, own or no"],
422424 ["archived", "Archived repositories", "put away, not gone: open one or restore it"],
test/security-floor-routes.test.ts +1
@@ -131,6 +131,7 @@ const UNSEEDED: Record<string, string> = {
131131 "/home/archived/:op": ARCH,
132132 "/migrate/jobs/:job": MIGRATE,
133133 "/now/:stage": NOW,
134 "/offers/:id": "needs a fork offer receipt, which the seed has none of",
134135 "/origins/:id/r/:owner/:name": ORIGIN,
135136 "/origins/:id/r/:owner/:name/blob/:ref/*path": ORIGIN,
136137 "/origins/:id/r/:owner/:name/branches": ORIGIN,

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs