Public: anyone can read this; the crew can change it.
A public app's page tells an outside agent in its first 500 bytes how to report a problem and offer a change #13702
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13662-a-public-app-s-page-tells-an-outside-age → main 6 commits fork 2 threads · 2 unresolved
8 files
changed +202
−2
docs/features/muse-test.md +14
| @@ -25,3 +25,17 @@ The door is open, so its limits hold: 3 reports a minute per source, 20 per | ||
| 25 | 25 | repository, 60 for the forge, 100 waiting per repository, and a request body |
| 26 | 26 | of at most 64 KiB (`413`). `test/muse-journey.test.ts` walks all of this |
| 27 | 27 | end to end and asserts the limits. |
| 28 | ||
| 29 | ## Where the doors are written | |
| 30 | ||
| 31 | - **Web:** a public repository's page carries both doors in its first 500 | |
| 32 | bytes (`<link rel="help">` to the report page and the JSON reports endpoint, | |
| 33 | and `/api/v1/contribute` only when outside contributions are open), the same | |
| 34 | URLs in its JSON-LD `potentialAction`, and in its `AGENTS.md` llms text. A | |
| 35 | private repository, or one whose reports are closed, gets no doors and no | |
| 36 | JSON-LD. | |
| 37 | - **Terminal:** on a public repository's screen, `:` lists "How outsiders | |
| 38 | report or offer"; it names `/owner/name/report`, `POST /api/v1/repos/owner/name/reports` | |
| 39 | and, when contributions are open, `POST /api/v1/contribute`. Private or | |
| 40 | reports-closed repositories list nothing. | |
| 41 | - Tests: `test/muse-find.test.ts`. |
src/tui/screens/report.ts +17
| @@ -9,7 +9,9 @@ import { openIssueThrough } from "../../actions/issues.ts"; | ||
| 9 | 9 | import { reportTitle } from "../../actions/page-report.ts"; |
| 10 | 10 | import { NOT_SENT_WORDS, SAY_SOMETHING_WORDS } from "../../actions/tell_words.ts"; |
| 11 | 11 | import { NOTE_TOO_LONG } from "../../apps/note_words.ts"; |
| 12 | import { takesOutside } from "../../actions/contribute_token.ts"; | |
| 12 | 13 | import { MAX_BODY } from "../../core/issues.ts"; |
| 14 | import { reportsClosed } from "../../core/reports.ts"; | |
| 13 | 15 | import type { Repo } from "../../core/repos.ts"; |
| 14 | 16 | import type { Ctx, Screen } from "../app/app.ts"; |
| 15 | 17 | import type { Command } from "../app/palette.ts"; |
| @@ -46,3 +48,18 @@ export function reportCommands(f: Session, ctx: Ctx, parent: () => Screen, repo: | ||
| 46 | 48 | }, |
| 47 | 49 | ]; |
| 48 | 50 | } |
| 51 | ||
| 52 | /** | |
| 53 | * The terminal twin of the page's report line (#13662): for a public | |
| 54 | * repository, one palette row that names where someone with no account | |
| 55 | * reports a problem and, when contributions are open, offers a change. | |
| 56 | * Nothing for a private repository or one whose reports are closed. | |
| 57 | */ | |
| 58 | export function outsideDoorsCommands(f: Session, ctx: Ctx, repo: Repo | undefined): Command[] { | |
| 59 | if (repo === undefined || repo.visibility !== "public" || reportsClosed(f.app.db, repo.id)) return []; | |
| 60 | const name = `${repo.ownerName}/${repo.name}`; | |
| 61 | const said = `No account: report at /${name}/report or POST /api/v1/repos/${name}/reports${ | |
| 62 | takesOutside(f.app, repo) ? "; offer a change at POST /api/v1/contribute" : "" | |
| 63 | }`; | |
| 64 | return [{ id: "outside-doors", title: `${name} — How outsiders report or offer`, hint: "no account", run: () => ctx.toast(said) }]; | |
| 65 | } |
src/tui/screens/workspace.ts +2 −1
| @@ -162,7 +162,7 @@ import { | ||
| 162 | 162 | openOnWeb, |
| 163 | 163 | } from "./common.ts"; |
| 164 | 164 | import { noteCommands } from "./notes.ts"; |
| 165 | import { reportCommands } from "./report.ts"; | |
| 165 | import { outsideDoorsCommands, reportCommands } from "./report.ts"; | |
| 166 | 166 | import { offerCommands } from "./offer.ts"; |
| 167 | 167 | import { reportsCommands } from "./reports.ts"; |
| 168 | 168 | import { tellCommands } from "./tell.ts"; |
| @@ -2171,6 +2171,7 @@ export function workspaceScreen( | ||
| 2171 | 2171 | ...workingCommands(f, ctx, repo), |
| 2172 | 2172 | ...tellCommands(f, ctx, () => screen, repo), |
| 2173 | 2173 | ...reportCommands(f, ctx, () => screen, repo), |
| 2174 | ...outsideDoorsCommands(f, ctx, repo), | |
| 2174 | 2175 | ...offerCommands(f, ctx, repo), |
| 2175 | 2176 | ...reportsCommands(f, ctx, repo), |
| 2176 | 2177 | ...noteCommands(f, ctx, () => screen, repo), |
src/web/doors_words.ts +1
| @@ -55,6 +55,7 @@ export function generatedAgentsMd(origin: string, owner: string, name: string, b | ||
| 55 | 55 | "3. Run the install and the tests above in your copy.", |
| 56 | 56 | "4. Send it: the forge opens the pull on push, or MCP `open_pull` with a `patch` and `checks`.", |
| 57 | 57 | `5. Found a problem and not a fix? ${origin}/${owner}/${name}/report needs no account. A sandbox needs one egress host: ${egressHost(origin)}.`, |
| 58 | ` As JSON: POST ${origin}/api/v1/repos/${owner}/${name}/reports {"title","body?","page?"}. Offer a change with no account (where the owner has opened it): ${origin}/api/v1/contribute.`, | |
| 58 | 59 | "", |
| 59 | 60 | ].join("\n") |
| 60 | 61 | ); |
src/web/layout.ts +6 −1
| @@ -826,6 +826,11 @@ export function page(options: PageOptions, status = 200): Response { | ||
| 826 | 826 | <html lang="en" ${theme ? html`data-theme="${theme}"` : null}> |
| 827 | 827 | <head> |
| 828 | 828 | <meta charset="utf-8" /> |
| 829 | ${ | |
| 830 | // How to report a problem or offer a change, before anything else | |
| 831 | // in the head: an agent that reads only the first bytes finds it. | |
| 832 | links.filter((l) => l.rel === "help").map((l) => html`<link rel="help" href="${l.href}" />`) | |
| 833 | } | |
| 829 | 834 | <meta |
| 830 | 835 | name="viewport" |
| 831 | 836 | content="width=device-width, initial-scale=1${options.keyboardResizes ? ", interactive-widget=resizes-content" : ""}" |
| @@ -866,7 +871,7 @@ export function page(options: PageOptions, status = 200): Response { | ||
| 866 | 871 | href="${OPENSEARCH_PATH}" |
| 867 | 872 | title="${OPENSEARCH_TITLE}" |
| 868 | 873 | /> |
| 869 | ${links.map( | |
| 874 | ${links.filter((l) => l.rel !== "help").map( | |
| 870 | 875 | (l) => |
| 871 | 876 | html`<link |
| 872 | 877 | rel="${l.rel}" |
src/web/pages/repo.ts +11
| @@ -27,6 +27,7 @@ import { lacks, NOT_A_MEMBER } from "../../core/roles.ts"; | ||
| 27 | 27 | import { storageLimitMessage } from "../../core/storage.ts"; |
| 28 | 28 | import { canRead, canWrite, listForks, type Repo } from "../../core/repos.ts"; |
| 29 | 29 | import { reportsClosed } from "../../core/reports.ts"; |
| 30 | import { repoStructuredData } from "../structured_data.ts"; | |
| 30 | 31 | import { capReached, lowWallet, monthCap } from "../../core/wallet.ts"; |
| 31 | 32 | import { takesOutside } from "../../actions/contribute_token.ts"; |
| 32 | 33 | import { FORKS_PER_DAY, forkRepo, repositoryLimitMessage } from "../../actions/repos.ts"; |
| @@ -1413,6 +1414,14 @@ function walletLine(ctx: Ctx, repo: Repo): Html | null { | ||
| 1413 | 1414 | return html`<p class="muted small mt" id="wallet-line">${said} <a href="${repoBase(repo)}/wallet">Wallet</a></p>`; |
| 1414 | 1415 | } |
| 1415 | 1416 | |
| 1417 | /** The page's JSON-LD: the outside doors of a public repository, none for any other. */ | |
| 1418 | function ldOf(ctx: Ctx, repo: Repo): { jsonLd?: string } { | |
| 1419 | if (repo.visibility !== "public" || reportsClosed(ctx.app.db, repo.id)) return {}; | |
| 1420 | const path = `${repo.ownerName}/${repo.name}`; | |
| 1421 | const doors = { report: `/api/v1/repos/${path}/reports`, ...(takesOutside(ctx.app, repo) ? { offer: "/api/v1/contribute" } : {}) }; | |
| 1422 | return { jsonLd: repoStructuredData(ctx.url.origin, path, repoLine({ private: false, name: repo.name, description: repo.description }), doors) }; | |
| 1423 | } | |
| 1424 | ||
| 1416 | 1425 | /** |
| 1417 | 1426 | * The one visible line on a public repository's front page that says how |
| 1418 | 1427 | * someone with no account reports a problem or offers a change, or that the |
| @@ -1487,6 +1496,7 @@ async function codeHome(ctx: Ctx, repo: Repo): Promise<Response> { | ||
| 1487 | 1496 | description: repoLine({ private: repo.visibility === "private", name: repo.name, description: repo.description }), |
| 1488 | 1497 | ogImage: `/og/repo/${repo.ownerName}~${repo.name}.png`, |
| 1489 | 1498 | about: `${repo.ownerName}/${repo.name}`, |
| 1499 | ...ldOf(ctx, repo), | |
| 1490 | 1500 | feed: { |
| 1491 | 1501 | href: `${repoBase(repo)}/activity.atom`, |
| 1492 | 1502 | title: `${repo.ownerName}/${repo.name} activity`, |
| @@ -1571,6 +1581,7 @@ async function codeHome(ctx: Ctx, repo: Repo): Promise<Response> { | ||
| 1571 | 1581 | description: repoLine({ private: repo.visibility === "private", name: repo.name, description: repo.description }), |
| 1572 | 1582 | ogImage: `/og/repo/${repo.ownerName}~${repo.name}.png`, |
| 1573 | 1583 | about: `${repo.ownerName}/${repo.name}`, |
| 1584 | ...ldOf(ctx, repo), | |
| 1574 | 1585 | feed: { |
| 1575 | 1586 | href: `${repoBase(repo)}/activity.atom`, |
| 1576 | 1587 | title: `${repo.ownerName}/${repo.name} activity`, |
src/web/structured_data.ts +21
| @@ -41,3 +41,24 @@ export function siteStructuredData(origin: string, version: string): string { | ||
| 41 | 41 | ], |
| 42 | 42 | }); |
| 43 | 43 | } |
| 44 | ||
| 45 | /** | |
| 46 | * A public repository's structured data: the code, and the two doors an | |
| 47 | * outside agent may use, as the same URLs the page's head and Link header name. | |
| 48 | * `offer` is absent where the owner has not opened contributions. | |
| 49 | */ | |
| 50 | export function repoStructuredData(origin: string, path: string, description: string, doors: { report?: string; offer?: string }): string { | |
| 51 | const action = (name: string, target: string) => ({ "@type": "CommunicateAction", name, target: `${origin}${target}` }); | |
| 52 | return safeJson({ | |
| 53 | "@context": "https://schema.org", | |
| 54 | "@type": "SoftwareSourceCode", | |
| 55 | "@id": `${origin}/${path}#code`, | |
| 56 | name: path, | |
| 57 | url: `${origin}/${path}`, | |
| 58 | description, | |
| 59 | potentialAction: [ | |
| 60 | ...(doors.report === undefined ? [] : [action("Report a problem", `/${path}/report`), action("Report a problem as JSON (POST)", doors.report)]), | |
| 61 | ...(doors.offer === undefined ? [] : [action("Offer a change", doors.offer)]), | |
| 62 | ], | |
| 63 | }); | |
| 64 | } |
test/muse-find.test.ts added +130
| @@ -0,0 +1,130 @@ | ||
| 1 | /** | |
| 2 | * The Muse test, at the first bytes (#13662): an anonymous agent fetching a | |
| 3 | * public repository's page finds both doors, report and offer, within 500 | |
| 4 | * bytes of the body, again in its JSON-LD, and in the repository's llms text. | |
| 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 } from "../src/app.ts"; | |
| 11 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 12 | import { createUser, getUserByName } from "../src/core/users.ts"; | |
| 13 | import { setReportsClosed } from "../src/core/reports.ts"; | |
| 14 | import { createForgeApp } from "../src/tui/forge.ts"; | |
| 15 | import { headlessTerminal } from "../src/tui/term/terminal.ts"; | |
| 16 | import { outsideDoorsCommands } from "../src/tui/screens/report.ts"; | |
| 17 | import { createRepo, getRepo } from "../src/core/repos.ts"; | |
| 18 | import { setOutsideContributions } from "../src/actions/contribute_token.ts"; | |
| 19 | import { commitFiles } from "../src/git/write.ts"; | |
| 20 | import { repoDir } from "../src/git/repos.ts"; | |
| 21 | import { quietLogs } from "./helpers/globals.ts"; | |
| 22 | ||
| 23 | quietLogs(); | |
| 24 | ||
| 25 | let dataDir: string; | |
| 26 | let app: ReturnType<typeof createApp>; | |
| 27 | let servers: Servers; | |
| 28 | ||
| 29 | beforeAll(async () => { | |
| 30 | dataDir = await mkdtemp(join(tmpdir(), "forge-muse-find-")); | |
| 31 | app = createApp({ dataDir, port: 0 }); | |
| 32 | servers = await serve(app); | |
| 33 | const a = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 34 | if (!a.ok) throw new Error(a.error); | |
| 35 | for (const [name, visibility] of [["notes", "public"], ["diary", "private"]] as const) { | |
| 36 | const r = await createRepo(app.db, app.reposRoot, { ownerId: a.value.id, name, visibility }); | |
| 37 | if (!r.ok) throw new Error(String(r.error)); | |
| 38 | await commitFiles(repoDir(app.reposRoot, "alice", name), { branch: "main", message: "readme", files: [{ path: "README.md", content: "# hi\n" }], author: { name: "a", email: "[email protected]" } }); | |
| 39 | } | |
| 40 | if (!setOutsideContributions(app, a.value, getRepo(app.db, "alice", "notes")!, true).ok) throw new Error("not opened"); | |
| 41 | }); | |
| 42 | ||
| 43 | afterAll(async () => { | |
| 44 | servers.stop(); | |
| 45 | app.close(); | |
| 46 | await rm(dataDir, { recursive: true, force: true }); | |
| 47 | }); | |
| 48 | ||
| 49 | const get = (path: string) => fetch(`${servers.url}${path}`, { headers: { accept: "text/html" } }); | |
| 50 | const REPORT = "/alice/notes/report"; | |
| 51 | const JSON_REPORT = "/api/v1/repos/alice/notes/reports"; | |
| 52 | const OFFER = "/api/v1/contribute"; | |
| 53 | ||
| 54 | test("both doors are in the first 500 bytes of a public repository's page", async () => { | |
| 55 | const res = await get("/alice/notes"); | |
| 56 | expect(res.status).toBe(200); | |
| 57 | const first = (await res.text()).slice(0, 500); | |
| 58 | expect(first).toContain(`href="${REPORT}"`); | |
| 59 | expect(first).toContain(`href="${JSON_REPORT}"`); | |
| 60 | expect(first).toContain(`href="${OFFER}"`); | |
| 61 | }); | |
| 62 | ||
| 63 | test("the same URLs are in the page's JSON-LD and the repository's llms text", async () => { | |
| 64 | const html = await (await get("/alice/notes")).text(); | |
| 65 | const ld = /<script type="application\/ld\+json">(.*?)<\/script>/s.exec(html)![1]!; | |
| 66 | const data = JSON.parse(ld); | |
| 67 | const targets = data.potentialAction.map((a: { target: string }) => a.target); | |
| 68 | for (const u of [REPORT, JSON_REPORT, OFFER]) expect(targets).toContain(`${servers.url}${u}`); | |
| 69 | const llms = await (await get("/alice/notes/AGENTS.md")).text(); | |
| 70 | for (const u of [REPORT, JSON_REPORT, OFFER]) expect(llms).toContain(u); | |
| 71 | }); | |
| 72 | ||
outdated
Vacuous: this string is unlikely to match the real markup, so the test passes even if JSON-LD leaks. Assert on parsed ld+json scripts. Also cover reports-closed and contributions-not-opened. |
||
| 73 | /** Every JSON-LD script on a page, parsed. */ | |
| 74 | function ldScripts(html: string): { "@type"?: string }[] { | |
| 75 | return [...html.matchAll(/<script[^>]*type="application\/ld\+json"[^>]*>(.*?)<\/script>/gs)].map((m) => JSON.parse(m[1]!)); | |
| 76 | } | |
| 77 | ||
| 78 | test("a private repository offers nothing to a stranger", async () => { | |
| 79 | const html = await (await get("/alice/diary")).text(); | |
| 80 | expect(html).not.toContain("/alice/diary/report"); | |
| 81 | expect(ldScripts(html).filter((d) => d["@type"] === "SoftwareSourceCode")).toEqual([]); | |
| 82 | expect(ldScripts(html)).toEqual([]); | |
| 83 | }); | |
| 84 | ||
| 85 | test("a public repository with reports closed gets no doors and no JSON-LD", async () => { | |
| 86 | const user = getUserByName(app.db, "alice")!; | |
| 87 | const r = await createRepo(app.db, app.reposRoot, { ownerId: user.id, name: "shut", visibility: "public" }); | |
| 88 | if (!r.ok) throw new Error(String(r.error)); | |
| 89 | await commitFiles(repoDir(app.reposRoot, "alice", "shut"), { branch: "main", message: "readme", files: [{ path: "README.md", content: "# hi\n" }], author: { name: "a", email: "[email protected]" } }); | |
| 90 | setReportsClosed(app.db, getRepo(app.db, "alice", "shut")!.id, true); | |
| 91 | const html = await (await get("/alice/shut")).text(); | |
| 92 | expect(html.slice(0, 500)).not.toContain("/alice/shut/report"); | |
| 93 | expect(html).not.toContain("/api/v1/repos/alice/shut/reports"); | |
| 94 | expect(ldScripts(html)).toEqual([]); | |
| 95 | }); | |
| 96 | ||
| 97 | test("without opened contributions the offer door is absent everywhere", async () => { | |
| 98 | const user = getUserByName(app.db, "alice")!; | |
| 99 | const r = await createRepo(app.db, app.reposRoot, { ownerId: user.id, name: "plain", visibility: "public" }); | |
| 100 | if (!r.ok) throw new Error(String(r.error)); | |
| 101 | await commitFiles(repoDir(app.reposRoot, "alice", "plain"), { branch: "main", message: "readme", files: [{ path: "README.md", content: "# hi\n" }], author: { name: "a", email: "[email protected]" } }); | |
| 102 | const html = await (await get("/alice/plain")).text(); | |
| 103 | expect(html.slice(0, 500)).toContain("/api/v1/repos/alice/plain/reports"); | |
| 104 | expect(html).not.toContain(OFFER); | |
| 105 | const targets = ldScripts(html).flatMap((d) => (d as { potentialAction?: { target: string }[] }).potentialAction ?? []).map((a) => a.target); | |
| 106 | expect(targets.length).toBeGreaterThan(0); | |
| 107 | expect(targets.some((t) => t.endsWith(OFFER))).toBe(false); | |
| 108 | }); | |
| 109 | ||
| 110 | test("the terminal's palette names the same doors, only where the page does", () => { | |
| 111 | const user = getUserByName(app.db, "alice")!; | |
| 112 | const { app: tui, session } = createForgeApp( | |
| 113 | app, | |
| 114 | { sshUsername: "alice", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user }, | |
| 115 | { terminal: headlessTerminal(120, 40), exitHooks: false }, | |
| 116 | ); | |
| 117 | const toasts: string[] = []; | |
| 118 | const ctx = { ...tui.ctx, toast: (t: string) => void toasts.push(t) }; | |
| 119 | const row = (name: string) => outsideDoorsCommands(session, ctx, getRepo(app.db, "alice", name)!); | |
| 120 | const said = (name: string): string => { | |
| 121 | row(name)[0]!.run(); | |
| 122 | return toasts.pop()!; | |
| 123 | }; | |
| 124 | expect(row("notes")).toHaveLength(1); | |
| 125 | const open = said("notes"); | |
| 126 | for (const u of [REPORT, JSON_REPORT, OFFER]) expect(open).toContain(u); | |
| 127 | expect(said("plain")).not.toContain(OFFER); | |
| 128 | expect(row("diary")).toEqual([]); | |
| 129 | expect(row("shut")).toEqual([]); | |
| 130 | }); |
new above
offline
Both doors: the terminal repository screen needs the same pointers, plus docs/features/<name>.md for the how-to.