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

The page manifest says what you can do here as who you are: /api/v1/here answers differently for a stranger, a member and an admin, and a test pins each #10399

Parked opened this
Closed without merging

mason/forge:mason/10384-the-page-manifest-says-what-you-can-do-h → main 9 commits fork 1 thread · 1 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +183 −10
docs/MCP.md +10
@@ -265,6 +265,16 @@ answers
265265 `POST …/issues/{number}/dependencies` and
266266 `DELETE …/issues/{number}/dependencies/{blocker}`. `test/openapi.test.ts` fails
267267 when the manifest names a route it lacks.
268 - **The manifest's shape.** `GET /api/v1/here?path=` (and the `here` tool)
269 answers `{ here, you, actions, can, mcp, docs }`. `can` appears on a
270 repository's page: a map of verb to the MCP tool that does it, or its route
271 when there is no tool (`"make it yours": "make_it_yours"`). It is the
272 caller's own: a stranger gets read and report, a signed-in non-member adds
273 issue, comment and offering a change, a writer adds merge, approve and tell,
274 an admin adds settings. A verb the caller cannot do, or that needs an account
275 or a proven email they lack, is absent, never listed and refused. A private
276 repository answers exactly as a missing one. `test/here-roles.test.ts` pins
277 each role.
268278 - **Where a tell came from.** `tell` takes `context`: `page` (http/https),
269279 `run`, `commit` (hex) and `said` (the person's words). Malformed context is
270280 refused; the rest is appended to the issue body. `tell` also takes `from`: a
scripts/unreached-allow.json −1
@@ -15,7 +15,6 @@
1515 "src/flow/review_rounds.ts",
1616 "src/flow/shared_red.ts",
1717 "src/flow/stale_fold.ts",
18 "src/kernel/why_now.ts",
1918 "src/spawn/pod.ts",
2019 "src/tui/gallery.ts",
2120 "src/tui/ui/qr.ts",
src/actions/here.ts +20 −1
@@ -85,6 +85,12 @@ export interface Manifest {
8585 readonly scope?: "ro";
8686 };
8787 readonly actions: readonly Action[];
88 /**
89 * On a repository's page: the verbs the caller can do right now, each with
90 * the MCP tool that does it, or else its route. A verb that needs an
91 * account or a proven email the caller lacks is absent, not listed.
92 */
93 readonly can?: Readonly<Record<string, string>>;
8894 readonly mcp: { readonly url: string; readonly oauth: string };
8995 readonly docs: string;
9096 }
@@ -195,6 +201,7 @@ export function manifestFor(
195201 /^[1-9]\d*$/.test(number)
196202 ? getPull(app.db, repo.id, Number(number))
197203 : undefined;
204 const actions = repoActions(app, repo, viewer, scope);
198205 return ok({
199206 here: {
200207 ...repoHere(app, repo, viewer),
@@ -208,11 +215,23 @@ export function manifestFor(
208215 }),
209216 },
210217 you: youFor(viewer, scope, repo, app),
211 actions: repoActions(app, repo, viewer, scope),
218 actions,
219 can: canOf(actions),
212220 ...common,
213221 });
214222 }
215223
224 /** The verbs open to the caller as they are: tool when there is one, else route. */
225 function canOf(actions: readonly Action[]): Record<string, string> {
226 const out: Record<string, string> = {};
227 for (const a of actions) {
228 if (a.account === true || a.verify === true) continue;
229 const via = a.mcp ?? a.http ?? a.ssh;
230 if (via !== undefined) out[a.do] = via;
231 }
232 return out;
233 }
234
216235 function youFor(
217236 viewer: User | undefined,
218237 scope: TokenScope | undefined,
src/crew/sandbox.ts +10 −6
@@ -179,13 +179,17 @@ export function dataInTemp(data: string): boolean {
179179
180180 function tempDenied(data: string, tmpDir: string | undefined): string[] {
181181 const temp = tmpdir();
182 const ownRunTmp = tmpDir !== undefined && !inside(data, tmpDir) && inside(temp, tmpDir) ? basename(tmpDir) : undefined;
183 if (dataInTemp(data)) {
184 // Never everything else there: the data directory itself is one of the entries.
185 return [
186 join(temp, `claude-${process.getuid?.() ?? 0}`),
187 ...others(temp, ownRunTmp ?? "").filter((path) => /^f[cr]-/.test(basename(path))),
188 ];
189 }
182190 // The run's own temp directory is in it (`runTmpDir`): everything else there is denied.
183 if (tmpDir !== undefined && !inside(data, tmpDir) && inside(temp, tmpDir)) return others(temp, basename(tmpDir));
184 if (!dataInTemp(data)) return [temp];
185 return [
186 join(temp, `claude-${process.getuid?.() ?? 0}`),
187 ...others(temp, "").filter((path) => basename(path).startsWith("fc-")),
188 ];
191 if (ownRunTmp !== undefined) return others(temp, ownRunTmp);
192 return [temp];
189193 }
190194
191195 /** Denied by name whatever the listing says: what must never be read. */
test/child-quota.test.ts +3 −1
@@ -13,6 +13,7 @@ import { serve, type Servers } from "../src/http/server.ts";
1313 import { quotaRefusal } from "../src/spawn/quota.ts";
1414 import { usePlacement, useProbe } from "../src/spawn/door.ts";
1515 import { hostedPlacement, memoryBodies } from "../src/spawn/placement.ts";
16 import { SIZES } from "../src/spawn/sizes.ts";
1617 import { quietLogs } from "./helpers/globals.ts";
1718
1819 quietLogs();
@@ -101,7 +102,8 @@ describe("child quota", () => {
101102
102103 test("room for small but not large is refused only for large", async () => {
103104 clear();
104 process.env["FORGE_CHILD_MEMORY_MIB"] = "2000";
105 // "first" above holds one small already: room for a second small, not for a large.
106 process.env["FORGE_CHILD_MEMORY_MIB"] = String(2 * SIZES.small.memoryMiB);
105107 expect(quotaRefusal(dir, "small")).toBeUndefined();
106108 expect(quotaRefusal(dir, "large")).toContain("memory limit");
107109 });
test/crew-sandbox.test.ts +2 −1
@@ -314,7 +314,8 @@ describe("the shell sandbox denies the whole data directory but the agent's own
314314 const { denyRead, tmpDir } = policy();
315315 expect(denied(join(dataDir, "crew/scout/01repo/7"), denyRead)).toBe(false);
316316 expect(tmpDir).toBeDefined();
317 expect(tmpDir!.startsWith(join(dataDir, "crew/scout/.t/"))).toBe(true);
317 // Under the agent, unless a long temp path leaves its sockets no room (`runTmpDir`).
318 expect(tmpDir).toBe(runTmpDir(dataDir, "scout", runId));
318319 expect(denied(tmpDir!, denyRead)).toBe(false);
319320 });
320321
test/here-roles.test.ts added +138
@@ -0,0 +1,138 @@
1 /**
2 * The manifest's `can` is a checked promise (#10384): for one repository path
3 * it differs for a stranger, a signed-in non-member, a writer and an admin;
4 * a verb the caller cannot do is absent; a private repository answers exactly
5 * as a missing one.
6 */
7 import { afterAll, beforeAll, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { newApp } from "../src/actions/apps.ts";
12 import { createRepo } from "../src/actions/repos.ts";
13 import { createApp, type App } from "../src/app.ts";
14 import { addTeamMember, createOrg, createTeam } from "../src/core/orgs.ts";
15 import { createToken } from "../src/core/tokens.ts";
16 import { createUser, type User } from "../src/core/users.ts";
17 import { markVerified } from "../src/core/verify.ts";
18 import { serve, type Servers } from "../src/http/server.ts";
19 import { requestTiming } from "./helpers/request-timing.ts";
20 import { promote } from "./helpers/members.ts";
21
22 let dataDir = "";
23 let app: App, servers: Servers;
24 const tokens: Record<string, string> = {};
25
26 beforeAll(async () => {
27 dataDir = await mkdtemp(join(tmpdir(), "forge-here-roles-"));
28 app = createApp({ dataDir, port: 0 });
29 servers = await serve(app);
30 const users: Record<string, User> = {};
31 for (const [name, first] of [["alice", true], ["wes", false], ["carol", false]] as const) {
32 const made = await createUser(app.db, {
33 origin: "seed", trusted: true, username: name, email: `${name}@forge.local`,
34 password: "a-good-passphrase", adminIfFirst: first,
35 });
36 if (!made.ok) throw new Error(made.error);
37 users[name] = made.value;
38 markVerified(app.db, made.value.id, new Date().toISOString());
39 }
40 promote(app.db, ...Object.values(users));
41 const org = createOrg(app.db, "acme", users["alice"]!.id);
42 if (!org.ok) throw new Error(org.error);
43 const writers = createTeam(app.db, org.value.id, "Writers", "write");
44 if (!writers.ok) throw new Error(String(writers.error));
45 addTeamMember(app.db, writers.value, users["wes"]!.id);
46 const pub = await newApp(app, users["alice"]!, { name: "pub", owner: "acme", visibility: "public" });
47 if (!pub.ok) throw new Error(String(pub.error));
48 const vault = await createRepo(app, users["alice"]!, { name: "vault", owner: "acme", visibility: "private" });
49 if (!vault.ok) throw new Error(String(vault.error));
50 for (const n of Object.keys(users)) tokens[n] = createToken(app.db, users[n]!.id, "t", "rw").token;
51 }, 60_000);
52
53 afterAll(async () => {
54 servers.stop();
55 app.close();
56 await rm(dataDir, { recursive: true, force: true });
57 });
58
59 const here = (path: string, who?: string) =>
60 fetch(`${servers.url}/api/v1/here?path=${encodeURIComponent(path)}`, {
61 headers: who === undefined ? {} : { authorization: `Bearer ${tokens[who]}` },
62 });
63 const can = async (who?: string): Promise<Record<string, string>> => {
64 const res = await here("/acme/pub", who);
65 expect(res.status).toBe(200);
66 return ((await res.json()) as { can: Record<string, string> }).can;
67 };
68
69 test("can differs for a stranger, a non-member, a writer and an admin", async () => {
70 const [stranger, member, writer, admin] = [await can(), await can("carol"), await can("wes"), await can("alice")];
71 const verbs = (c: Record<string, string>) => Object.keys(c);
72 expect(verbs(stranger)).toContain("report a problem");
73 expect(verbs(stranger)).not.toContain("open an issue");
74 expect(verbs(member)).toContain("open an issue");
75 expect(verbs(member)).toContain("make it yours");
76 expect(verbs(member)).not.toContain("merge a pull");
77 expect(verbs(writer)).toContain("merge a pull");
78 expect(verbs(writer)).toContain("tell the crew");
79 expect(verbs(writer)).not.toContain("change settings");
80 expect(verbs(admin)).toContain("change settings");
81 expect(verbs(admin)).toContain("merge a pull");
82 const sizes = [stranger, member, writer, admin].map((c) => verbs(c).length);
83 expect(new Set(sizes).size).toBe(4);
84 });
85
86 test("a verb names the MCP tool with the button's words; a stranger is not offered what needs an account", async () => {
87 expect((await can("carol"))["make it yours"]).toBe("make_it_yours");
88 expect((await can("wes"))["tell the crew"]).toBe("tell");
89 expect((await can())["report a problem"]).toBe("report");
90 const stranger = await can();
91 for (const v of ["open an issue", "comment", "offer a change", "make it yours"])
92 expect(stranger[v]).toBeUndefined();
93 });
94
95 test("a private repository answers exactly as a missing one", async () => {
96 for (const who of [undefined, "carol"]) {
97 const hidden = await here("/acme/vault", who);
98 const missing = await here("/acme/nothing", who);
99 expect(hidden.status).toBe(404);
100 expect(await hidden.text()).toBe(await missing.text());
101 }
102 });
103
outdated

This is a size check, not the timing the issue asked for. Replace with a requestTiming-based assertion as in test/api-explore-timing.test.ts.

104 test("the manifest names its phases in order, each with a duration", async () => {
105 await here("/acme/pub", "alice");
106 const res = await here("/acme/pub", "alice");
107 await res.text();
108 const names = requestTiming(res).split(", ").map((p) => p.split(";")[0]!);
109 expect(names.slice(names.indexOf("app") + 1)).toEqual(["session", "here", "render"]);
110 for (const part of requestTiming(res).split(", "))
111 expect(Number(/dur=([\d.]+)/.exec(part)?.[1])).not.toBeNaN();
112 });
113
114 test("every verb that names an MCP tool names one in tools/list, spelled as its page button", async () => {
115 const tools = new Set<string>();
116 let cursor: string | undefined;
117 do {
118 const listed = await fetch(`${servers.url}/mcp`, {
119 method: "POST",
120 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${tokens["alice"]}` },
121 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: cursor === undefined ? {} : { cursor } }),
122 });
123 const page = ((await listed.json()) as { result: { tools: { name: string }[]; nextCursor?: string } }).result;
124 for (const t of page.tools) tools.add(t.name);
125 cursor = page.nextCursor;
126 } while (cursor !== undefined);
127 const web = (await Promise.all([...new Bun.Glob("**/*.ts").scanSync("src/web")].map((f) => Bun.file(`src/web/${f}`).text()))).join("\n");
128 let checked = 0;
129 for (const who of [undefined, "carol", "wes", "alice"]) {
130 for (const [verb, via] of Object.entries(await can(who))) {
131 if (!/^[a-z_]+$/.test(via)) continue; // a route, not a tool
132 checked++;
133 expect([verb, via, tools.has(via)]).toEqual([verb, via, true]);
134 expect(web).toContain(`"${verb[0]!.toUpperCase()}${verb.slice(1)}"`);
135 }
136 }
137 expect(checked).toBeGreaterThanOrEqual(3);
138 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs