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
scout/forge:scout/8066-an-admin-sets-the-repository-s-descripti → main 3 commits fork
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 | ||
| 65 | 65 | |
| 66 | 66 | 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. |
| 67 | 67 | |
| 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 | ||
| 68 | 70 | 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. |
| 69 | 71 | |
| 70 | 72 | 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 { | ||
| 57 | 57 | type FileWrite, |
| 58 | 58 | } from "../git/write.ts"; |
| 59 | 59 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 60 | import { checkDescription } from "../core/repo_description.ts"; | |
| 60 | 61 | import { trackPullHead } from "../core/pulls.ts"; |
| 61 | 62 | import { |
| 62 | 63 | requireParticipant, |
| @@ -282,7 +283,7 @@ export async function privateRepoForSealed( | ||
| 282 | 283 | return sealedForkFor(app, actor, base); |
| 283 | 284 | } |
| 284 | 285 | |
| 285 | export type UpdateSettingsError = "not_found" | "unknown_branch"; | |
| 286 | export type UpdateSettingsError = "not_found" | "unknown_branch" | "invalid_description"; | |
| 286 | 287 | |
| 287 | 288 | /** Each repository's archive transitions, one after another. */ |
| 288 | 289 | const archiveTurns = new WeakMap<App, Map<string, Promise<void>>>(); |
| @@ -386,6 +387,11 @@ export async function updateRepoSettings( | ||
| 386 | 387 | // base, whoever owns it (`core/sealed.ts`). |
| 387 | 388 | if (repo.sealedFor !== null && settings.visibility === "public") |
| 388 | 389 | 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 | } | |
| 389 | 395 | const branch = settings.defaultBranch; |
| 390 | 396 | if (branch !== undefined && branch !== repo.defaultBranch) { |
| 391 | 397 | 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 @@ | ||
| 1 | 1 | import { updateRepoSettings } from "../../../actions/repos.ts"; |
| 2 | 2 | import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; |
| 3 | import { DESCRIPTION_WORDS } from "../../../core/repo_description.ts"; | |
| 3 | 4 | import { VISIBILITY_WORDS } from "../../../core/arg_words.ts"; |
| 4 | 5 | |
| 5 | 6 | export const tool: Tool = { |
| @@ -30,6 +31,8 @@ export const tool: Tool = { | ||
| 30 | 31 | ...(visibility !== undefined ? { visibility } : {}), |
| 31 | 32 | ...(description !== undefined ? { description } : {}), |
| 32 | 33 | }); |
| 34 | if (!updated.ok && updated.error === "invalid_description") | |
| 35 | return bad("invalid", DESCRIPTION_WORDS); | |
| 33 | 36 | if (!updated.ok) |
| 34 | 37 | return bad(updated.error === "not_found" ? "not_found" : "forbidden", updated.error); |
| 35 | 38 | return good({ |
src/tui/screens/about.ts +28 −1
| @@ -16,6 +16,7 @@ | ||
| 16 | 16 | */ |
| 17 | 17 | |
| 18 | 18 | import { audienceFor } from "../../core/audience.ts"; |
| 19 | import { DESCRIPTION_WORDS } from "../../core/repo_description.ts"; | |
| 19 | 20 | import { isPinned } from "../../core/pins.ts"; |
| 20 | 21 | import { parentReleases, releasesSentence } from "../../core/parent_releases.ts"; |
| 21 | 22 | import { running } from "../../kernel/version.ts"; |
| @@ -71,7 +72,7 @@ import { style } from "../term/style.ts"; | ||
| 71 | 72 | import { truncate, wrap } from "../term/width.ts"; |
| 72 | 73 | import { badge, card } from "../ui/widgets.ts"; |
| 73 | 74 | 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"; | |
| 75 | 76 | import { connectionsScreen, egressScreen } from "./egress.ts"; |
| 76 | 77 | import { eventsScreen } from "./events.ts"; |
| 77 | 78 | import { newPullScreen } from "./newpull.ts"; |
| @@ -232,6 +233,8 @@ export function aboutScreen( | ||
| 232 | 233 | ...(f.user?.isAdmin === true && repo !== undefined |
| 233 | 234 | ? [binding(["e"], "egress"), binding(["c"], "connections")] |
| 234 | 235 | : []), |
| 236 | // The one-line description is an admin's, as Settings has it. | |
| 237 | ...(mayPerson() ? [binding(["w"], "describe")] : []), | |
| 235 | 238 | ...(offered === null |
| 236 | 239 | ? [] |
| 237 | 240 | : [ |
| @@ -484,6 +487,30 @@ export function aboutScreen( | ||
| 484 | 487 | }); |
| 485 | 488 | return true; |
| 486 | 489 | } |
| 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 | } | |
| 487 | 514 | if (e.key === "t" && repo !== undefined && mayTrail()) { |
| 488 | 515 | const shown = getProvenance(f.db, repo.id)?.shown === true; |
| 489 | 516 | const done = showProvenance(f.app, f.user, repo, !shown); |
src/web/pages/settings.ts +4 −1
| @@ -8,6 +8,7 @@ | ||
| 8 | 8 | * same-origin POST and every one of them says what happened. |
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | import { DESCRIPTION_WORDS } from "../../core/repo_description.ts"; | |
| 11 | 12 | import { appLimitWords } from "../../actions/app_limit.ts"; |
| 12 | 13 | import { showProvenance } from "../../actions/provenance.ts"; |
| 13 | 14 | import { getProvenance, parentUrl, sourceLabel } from "../../core/provenance.ts"; |
| @@ -457,7 +458,9 @@ export async function settingsUpdate(ctx: Ctx): Promise<Response> { | ||
| 457 | 458 | message: |
| 458 | 459 | updated.error === "unknown_branch" |
| 459 | 460 | ? "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.", | |
| 461 | 464 | }; |
| 462 | 465 | return flashTo(ctx, `${base}/settings`, flash); |
| 463 | 466 | } |
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 | }); |
new above
offline