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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13662-a-public-app-s-page-tells-an-outside-age → main 6 commits fork 2 threads · 2 unresolved

  • Merged. scout/13662-a-public-app-s-page-tells-an-outside-age was merged into main as 6d30f7f.

Review

Sign in to review this change.
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
2525 repository, 60 for the forge, 100 waiting per repository, and a request body
2626 of at most 64 KiB (`413`). `test/muse-journey.test.ts` walks all of this
2727 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";
99 import { reportTitle } from "../../actions/page-report.ts";
1010 import { NOT_SENT_WORDS, SAY_SOMETHING_WORDS } from "../../actions/tell_words.ts";
1111 import { NOTE_TOO_LONG } from "../../apps/note_words.ts";
12 import { takesOutside } from "../../actions/contribute_token.ts";
1213 import { MAX_BODY } from "../../core/issues.ts";
14 import { reportsClosed } from "../../core/reports.ts";
1315 import type { Repo } from "../../core/repos.ts";
1416 import type { Ctx, Screen } from "../app/app.ts";
1517 import type { Command } from "../app/palette.ts";
@@ -46,3 +48,18 @@ export function reportCommands(f: Session, ctx: Ctx, parent: () => Screen, repo:
4648 },
4749 ];
4850 }
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 {
162162 openOnWeb,
163163 } from "./common.ts";
164164 import { noteCommands } from "./notes.ts";
165 import { reportCommands } from "./report.ts";
165 import { outsideDoorsCommands, reportCommands } from "./report.ts";
166166 import { offerCommands } from "./offer.ts";
167167 import { reportsCommands } from "./reports.ts";
168168 import { tellCommands } from "./tell.ts";
@@ -2171,6 +2171,7 @@ export function workspaceScreen(
21712171 ...workingCommands(f, ctx, repo),
21722172 ...tellCommands(f, ctx, () => screen, repo),
21732173 ...reportCommands(f, ctx, () => screen, repo),
2174 ...outsideDoorsCommands(f, ctx, repo),
21742175 ...offerCommands(f, ctx, repo),
21752176 ...reportsCommands(f, ctx, repo),
21762177 ...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
5555 "3. Run the install and the tests above in your copy.",
5656 "4. Send it: the forge opens the pull on push, or MCP `open_pull` with a `patch` and `checks`.",
5757 `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.`,
5859 "",
5960 ].join("\n")
6061 );
src/web/layout.ts +6 −1
@@ -826,6 +826,11 @@ export function page(options: PageOptions, status = 200): Response {
826826 <html lang="en" ${theme ? html`data-theme="${theme}"` : null}>
827827 <head>
828828 <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 }
829834 <meta
830835 name="viewport"
831836 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 {
866871 href="${OPENSEARCH_PATH}"
867872 title="${OPENSEARCH_TITLE}"
868873 />
869 ${links.map(
874 ${links.filter((l) => l.rel !== "help").map(
870875 (l) =>
871876 html`<link
872877 rel="${l.rel}"
src/web/pages/repo.ts +11
@@ -27,6 +27,7 @@ import { lacks, NOT_A_MEMBER } from "../../core/roles.ts";
2727 import { storageLimitMessage } from "../../core/storage.ts";
2828 import { canRead, canWrite, listForks, type Repo } from "../../core/repos.ts";
2929 import { reportsClosed } from "../../core/reports.ts";
30 import { repoStructuredData } from "../structured_data.ts";
3031 import { capReached, lowWallet, monthCap } from "../../core/wallet.ts";
3132 import { takesOutside } from "../../actions/contribute_token.ts";
3233 import { FORKS_PER_DAY, forkRepo, repositoryLimitMessage } from "../../actions/repos.ts";
@@ -1413,6 +1414,14 @@ function walletLine(ctx: Ctx, repo: Repo): Html | null {
14131414 return html`<p class="muted small mt" id="wallet-line">${said} <a href="${repoBase(repo)}/wallet">Wallet</a></p>`;
14141415 }
14151416
1417 /** The page's JSON-LD: the outside doors of a public repository, none for any other. */

Both doors: the terminal repository screen needs the same pointers, plus docs/features/<name>.md for the how-to.

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
14161425 /**
14171426 * The one visible line on a public repository's front page that says how
14181427 * 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> {
14871496 description: repoLine({ private: repo.visibility === "private", name: repo.name, description: repo.description }),
14881497 ogImage: `/og/repo/${repo.ownerName}~${repo.name}.png`,
14891498 about: `${repo.ownerName}/${repo.name}`,
1499 ...ldOf(ctx, repo),
14901500 feed: {
14911501 href: `${repoBase(repo)}/activity.atom`,
14921502 title: `${repo.ownerName}/${repo.name} activity`,
@@ -1571,6 +1581,7 @@ async function codeHome(ctx: Ctx, repo: Repo): Promise<Response> {
15711581 description: repoLine({ private: repo.visibility === "private", name: repo.name, description: repo.description }),
15721582 ogImage: `/og/repo/${repo.ownerName}~${repo.name}.png`,
15731583 about: `${repo.ownerName}/${repo.name}`,
1584 ...ldOf(ctx, repo),
15741585 feed: {
15751586 href: `${repoBase(repo)}/activity.atom`,
15761587 title: `${repo.ownerName}/${repo.name} activity`,
src/web/structured_data.ts +21
@@ -41,3 +41,24 @@ export function siteStructuredData(origin: string, version: string): string {
4141 ],
4242 });
4343 }
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs