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

An admin sets the repository's description from the terminal's About card with `w`, as Settings does #8135

Parked opened this
Closed without merging

scout/forge:scout/8066-an-admin-sets-the-repository-s-descripti → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +225 −3
README.md +2
@@ -65,6 +65,8 @@ Remove on a board panel asks first, on the confirm page, which names the panel a
6565
6666 A hold can be set "until green" (a checkbox on the hold form, `until: "green"` on the hold API and the MCP `hold` tool): when a check passes on the pull's current head the forge releases it and the pull's timeline says `hold released: green on <short oid>`. A plain hold is never released by a check.
6767
68 In the terminal, `w` on the About card (`I`) writes the repository's description: a one-line prompt prefilled with the current words, enter saves, esc leaves it. It is offered to an admin who is a person only (never an agent, a writer or a reader), and goes through `updateRepoSettings`, so it is audited like Settings, the API and MCP `repo_settings`. All four share one rule (`src/core/repo_description.ts`): trimmed, at most 2000 characters, no control characters; a refusal is a toast (a message on the other doors) and changes nothing.
69
6870 In the terminal, `h` on the pull screen asks for a one-line reason and holds the pull (an empty or over-200-character reason is refused in the prompt, as on the web and in MCP); on a held pull `h` asks to confirm and lets it go. Both go through `holdPull` and `releasePull`, so the header shows `held by <who>: <why>`. `h` is offered to a person who can write only: an agent or a reader does not get it.
6971
7072 A forge admin's terminal home ends its forge strip with `Builders idle: <word> (<link>)` while no builder is starting anything: `ceiling reached` (/meter), `flow only` (/map), `no subscription with headroom` (/subscriptions) or `nothing ready` (/map). `idleReason` in `src/crew/idle_reason.ts` names it, asking the dispatcher's own predicates (`atCeiling`, the holds of `held.ts`, `pace`); it says nothing while a builder slot is busy or something can start. The web home tile is the next piece.
src/actions/repos.ts +7 −1
@@ -57,6 +57,7 @@ import {
5757 type FileWrite,
5858 } from "../git/write.ts";
5959 import { err, ok, type Result } from "../kernel/result.ts";
60 import { checkDescription } from "../core/repo_description.ts";
6061 import { trackPullHead } from "../core/pulls.ts";
6162 import {
6263 requireParticipant,
@@ -282,7 +283,7 @@ export async function privateRepoForSealed(
282283 return sealedForkFor(app, actor, base);
283284 }
284285
285 export type UpdateSettingsError = "not_found" | "unknown_branch";
286 export type UpdateSettingsError = "not_found" | "unknown_branch" | "invalid_description";
286287
287288 /** Each repository's archive transitions, one after another. */
288289 const archiveTurns = new WeakMap<App, Map<string, Promise<void>>>();
@@ -386,6 +387,11 @@ export async function updateRepoSettings(
386387 // base, whoever owns it (`core/sealed.ts`).
387388 if (repo.sealedFor !== null && settings.visibility === "public")
388389 return err("not_found");
390 if (settings.description !== undefined) {
391 const kept = checkDescription(settings.description);
392 if (!kept.ok) return err("invalid_description");
393 settings = { ...settings, description: kept.value };
394 }
389395 const branch = settings.defaultBranch;
390396 if (branch !== undefined && branch !== repo.defaultBranch) {
391397 const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
src/core/repo_description.ts added +22
@@ -0,0 +1,22 @@
1 /**
2 * What a repository's description may be: one line of plain text, trimmed, at
3 * most DESCRIPTION_MAX characters. `updateRepoSettings` applies it, so
4 * Settings, the API, MCP `repo_settings` and the terminal share one rule.
5 */
6
7 export const DESCRIPTION_MAX = 2000;
8
9 /** The refusal, in one sentence for every door. */
10 export const DESCRIPTION_WORDS = `A description is one line of plain text, at most ${DESCRIPTION_MAX} characters.`;
11
12 /** The description as it is kept (trimmed), or why it is refused. */
13 export function checkDescription(
14 text: string,
15 ): { ok: true; value: string } | { ok: false } {
16 const value = text.trim();
17 if (/[\u0000-\u001f\u007f]/.test(value))
18 return { ok: false };
19 if ([...value].length > DESCRIPTION_MAX)
20 return { ok: false };
21 return { ok: true, value };
22 }
src/http/mcp/tools/repo_settings.ts +3
@@ -1,5 +1,6 @@
11 import { updateRepoSettings } from "../../../actions/repos.ts";
22 import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
3 import { DESCRIPTION_WORDS } from "../../../core/repo_description.ts";
34 import { VISIBILITY_WORDS } from "../../../core/arg_words.ts";
45
56 export const tool: Tool = {
@@ -30,6 +31,8 @@ export const tool: Tool = {
3031 ...(visibility !== undefined ? { visibility } : {}),
3132 ...(description !== undefined ? { description } : {}),
3233 });
34 if (!updated.ok && updated.error === "invalid_description")
35 return bad("invalid", DESCRIPTION_WORDS);
3336 if (!updated.ok)
3437 return bad(updated.error === "not_found" ? "not_found" : "forbidden", updated.error);
3538 return good({
src/tui/screens/about.ts +28 −1
@@ -16,6 +16,7 @@
1616 */
1717
1818 import { audienceFor } from "../../core/audience.ts";
19 import { DESCRIPTION_WORDS } from "../../core/repo_description.ts";
1920 import { isPinned } from "../../core/pins.ts";
2021 import { parentReleases, releasesSentence } from "../../core/parent_releases.ts";
2122 import { running } from "../../kernel/version.ts";
@@ -71,7 +72,7 @@ import { style } from "../term/style.ts";
7172 import { truncate, wrap } from "../term/width.ts";
7273 import { badge, card } from "../ui/widgets.ts";
7374 import type { Session } from "../session.ts";
74 import { PIN_MARK, ago, confirmScreen, drawFacts, plural } from "./common.ts";
75 import { PIN_MARK, ago, confirmScreen, drawFacts, plural, promptScreen } from "./common.ts";
7576 import { connectionsScreen, egressScreen } from "./egress.ts";
7677 import { eventsScreen } from "./events.ts";
7778 import { newPullScreen } from "./newpull.ts";
@@ -232,6 +233,8 @@ export function aboutScreen(
232233 ...(f.user?.isAdmin === true && repo !== undefined
233234 ? [binding(["e"], "egress"), binding(["c"], "connections")]
234235 : []),
236 // The one-line description is an admin's, as Settings has it.
237 ...(mayPerson() ? [binding(["w"], "describe")] : []),
235238 ...(offered === null
236239 ? []
237240 : [
@@ -484,6 +487,30 @@ export function aboutScreen(
484487 });
485488 return true;
486489 }
490 if (e.key === "w" && repo !== undefined && mayPerson()) {
491 const at = repo;
492 ctx.push(
493 promptScreen(ctx, screen, {
494 title: "Description",
495 label: "What is this repository for?",
496 value: at.description,
497 onSubmit: async (text) => {
498 const done = await updateRepoSettings(f.app, f.user, at, { description: text });
499 if (done.ok) {
500 repo = getRepoById(f.db, done.value.id) ?? done.value;
501 rows = factRows();
502 ctx.toast("description saved", "success");
503 } else
504 ctx.toast(
505 done.error === "invalid_description" ? DESCRIPTION_WORDS : "that could not be changed",
506 "danger",
507 );
508 ctx.invalidate();
509 },
510 }),
511 );
512 return true;
513 }
487514 if (e.key === "t" && repo !== undefined && mayTrail()) {
488515 const shown = getProvenance(f.db, repo.id)?.shown === true;
489516 const done = showProvenance(f.app, f.user, repo, !shown);
src/web/pages/settings.ts +4 −1
@@ -8,6 +8,7 @@
88 * same-origin POST and every one of them says what happened.
99 */
1010
11 import { DESCRIPTION_WORDS } from "../../core/repo_description.ts";
1112 import { appLimitWords } from "../../actions/app_limit.ts";
1213 import { showProvenance } from "../../actions/provenance.ts";
1314 import { getProvenance, parentUrl, sourceLabel } from "../../core/provenance.ts";
@@ -457,7 +458,9 @@ export async function settingsUpdate(ctx: Ctx): Promise<Response> {
457458 message:
458459 updated.error === "unknown_branch"
459460 ? "That branch does not exist in this repository."
460 : "Those settings could not be saved.",
461 : updated.error === "invalid_description"
462 ? DESCRIPTION_WORDS
463 : "Those settings could not be saved.",
461464 };
462465 return flashTo(ctx, `${base}/settings`, flash);
463466 }
test/tui-about-description.test.ts added +159
@@ -0,0 +1,159 @@
1 /**
2 * The description at the terminal's door (issue #8066, pull #8135): on the About card, an admin
3 * who is a person writes the one-line description with `w`; esc leaves it, a
4 * refusal is a toast, and a writer or an agent is not offered the key.
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 { createApp, type App } from "../src/app.ts";
11 import { createAgent } from "../src/actions/crew.ts";
12 import { addTeamMember, createOrg, createTeam } from "../src/core/orgs.ts";
13 import { DESCRIPTION_WORDS } from "../src/core/repo_description.ts";
14 import { createRepo, getRepoById, type Repo } from "../src/core/repos.ts";
15 import { createUser, type User } from "../src/core/users.ts";
16 import type { Ctx, Screen } from "../src/tui/app/app.ts";
17 import { aboutScreen } from "../src/tui/screens/about.ts";
18 import { theme } from "../src/tui/ui/theme.ts";
19 import { localSource } from "../src/view/local.ts";
20 import type { Session } from "../src/tui/session.ts";
21 import { quietLogs } from "./helpers/globals.ts";
22
23 quietLogs();
24
25 let dataDir: string;
26 let app: App;
27 let founder: User;
28 let writer: User;
29 let bot: User;
30 let repo: Repo;
31 let botRepo: Repo;
32
33 const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
34 if (!r.ok) throw new Error(JSON.stringify(r.error));
35 return r.value;
36 };
37 async function until(what: string, done: () => boolean, ms = 5000): Promise<void> {
38 const end = Date.now() + ms;
39 while (!done()) {
40 if (Date.now() > end) throw new Error(`timed out waiting for ${what}`);
41 await Bun.sleep(10);
42 }
43 }
44
45 function card(user: User, target: Repo = repo) {
46 const pushed: Screen[] = [];
47 const toasts: string[] = [];
48 const ctx = {
49 theme: theme("dark"),
50 invalidate() {},
51 toast: (t: string) => toasts.push(t),
52 push: (s: Screen) => pushed.push(s),
53 pop() {},
54 copy() {},
55 hit() {},
56 } as unknown as Ctx;
57 const f = { app, db: app.db, user } as unknown as Session;
58 const src = localSource(app, getRepoById(app.db, target.id)!, user);
59 const screen = aboutScreen(f, ctx, { render() {} } as unknown as Screen, src, undefined, "main");
60 const label = (key: string) => screen.keys.find((b) => b.keys.includes(key))?.help;
61 const press = (key: string) => screen.key!({ key } as never);
62 return { pushed, toasts, label, press };
63 }
64
65 beforeAll(async () => {
66 dataDir = await mkdtemp(join(tmpdir(), "forge-tui-description-"));
67 app = createApp({ dataDir, port: 0 });
68 const make = async (username: string, adminIfFirst = false) =>
69 ok(
70 await createUser(app.db, {
71 origin: "seed",
72 trusted: true,
73 username,
74 email: `${username}@forge.local`,
75 password: "a-good-passphrase",
76 adminIfFirst,
77 }),
78 );
79 const root = await make("founding", true);
80 founder = await make("founder");
81 writer = await make("writer");
82 const org = ok(createOrg(app.db, "acme", founder.id));
83 ok(await createRepo(app.db, app.reposRoot, { ownerId: org.id, name: "site", visibility: "public" }));
84 repo = getRepoById(app.db, (app.db.query("SELECT id FROM repo WHERE name = 'site'").get() as { id: string }).id)!;
85 addTeamMember(app.db, ok(createTeam(app.db, org.id, "Writers", "write")), writer.id);
86 bot = ok(await createAgent(app, root, { username: "bot" })).user;
87 // An agent never sits on an admin team; it administers what it owns.
88 botRepo = ok(await createRepo(app.db, app.reposRoot, { ownerId: bot.id, name: "own", visibility: "public" }));
89 }, 30_000);
90
91 afterAll(async () => {
92 app?.close();
93 await rm(dataDir, { recursive: true, force: true });
94 });
95
96 const description = () => getRepoById(app.db, repo.id)!.description;
97 const type = (screen: Screen, text: string) => {
98 for (const ch of text) screen.key!({ key: ch } as never);
99 };
100 /** The trail's lines naming a description change, as web viewers' live pages read them. */
101 const audited = () =>
102 (app.db.query("SELECT payload FROM event WHERE kind = 'repo.settings_updated' AND repo_id = ?1").all(repo.id) as {
103 payload: string;
104 }[]).filter((r) => r.payload.includes('"description"'));
105
106 test("an admin writes the description with w, enter saves and audits it", async () => {
107 const c = card(founder);
108 expect(c.label("w")).toBe("describe");
109 c.press("w");
110 const prompt = c.pushed[0]!;
111 type(prompt, "Our site");
112 prompt.key!({ key: "enter" } as never);
113 await until("saved", () => description() === "Our site");
114 await until("the toast", () => c.toasts.includes("description saved"));
115 const lines = audited();
116 expect(lines).toHaveLength(1);
117 expect(JSON.parse(lines[0]!.payload).changed.description).toEqual({ from: "", to: "Our site" });
118 });
119
120 test("esc leaves the description as it was", async () => {
121 const c = card(founder);
122 c.press("w");
123 type(c.pushed[0]!, " more");
124 c.pushed[0]!.key!({ key: "esc" } as never);
125 await Bun.sleep(20);
126 expect(description()).toBe("Our site");
127 });
128
129 test("a control character is refused with the shared words and changes nothing", async () => {
130 for (const bad of ["two\tcolumns", "esc\x1b[31m"]) {
131 const c = card(founder);
132 c.press("w");
133 type(c.pushed[0]!, bad);
134 c.pushed[0]!.key!({ key: "enter" } as never);
135 await until("the toast", () => c.toasts.length === 1);
136 expect(c.toasts[0]).toBe(DESCRIPTION_WORDS);
137 expect(description()).toBe("Our site");
138 }
139 expect(audited()).toHaveLength(1);
140 });
141
142 test("a refused description is a toast and changes nothing", async () => {
143 const c = card(founder);
144 c.press("w");
145 type(c.pushed[0]!, "x".repeat(2001));
146 c.pushed[0]!.key!({ key: "enter" } as never);
147 await until("the toast", () => c.toasts.length === 1);
148 expect(c.toasts[0]).toBe(DESCRIPTION_WORDS);
149 expect(description()).toBe("Our site");
150 });
151
152 test("a writer and an agent admin are not offered w, and it does nothing", () => {
153 for (const [who, at] of [[writer, repo], [bot, botRepo]] as const) {
154 const c = card(who, at);
155 expect(c.label("w")).toBeUndefined();
156 c.press("w");
157 expect(c.pushed).toHaveLength(0);
158 }
159 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs