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
mason/forge:mason/10384-the-page-manifest-says-what-you-can-do-h → main 9 commits fork 1 thread · 1 unresolved
7 files
changed +183
−10
docs/MCP.md +10
| @@ -265,6 +265,16 @@ answers | ||
| 265 | 265 | `POST …/issues/{number}/dependencies` and |
| 266 | 266 | `DELETE …/issues/{number}/dependencies/{blocker}`. `test/openapi.test.ts` fails |
| 267 | 267 | 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. | |
| 268 | 278 | - **Where a tell came from.** `tell` takes `context`: `page` (http/https), |
| 269 | 279 | `run`, `commit` (hex) and `said` (the person's words). Malformed context is |
| 270 | 280 | refused; the rest is appended to the issue body. `tell` also takes `from`: a |
scripts/unreached-allow.json −1
| @@ -15,7 +15,6 @@ | ||
| 15 | 15 | "src/flow/review_rounds.ts", |
| 16 | 16 | "src/flow/shared_red.ts", |
| 17 | 17 | "src/flow/stale_fold.ts", |
| 18 | "src/kernel/why_now.ts", | |
| 19 | 18 | "src/spawn/pod.ts", |
| 20 | 19 | "src/tui/gallery.ts", |
| 21 | 20 | "src/tui/ui/qr.ts", |
src/actions/here.ts +20 −1
| @@ -85,6 +85,12 @@ export interface Manifest { | ||
| 85 | 85 | readonly scope?: "ro"; |
| 86 | 86 | }; |
| 87 | 87 | 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>>; | |
| 88 | 94 | readonly mcp: { readonly url: string; readonly oauth: string }; |
| 89 | 95 | readonly docs: string; |
| 90 | 96 | } |
| @@ -195,6 +201,7 @@ export function manifestFor( | ||
| 195 | 201 | /^[1-9]\d*$/.test(number) |
| 196 | 202 | ? getPull(app.db, repo.id, Number(number)) |
| 197 | 203 | : undefined; |
| 204 | const actions = repoActions(app, repo, viewer, scope); | |
| 198 | 205 | return ok({ |
| 199 | 206 | here: { |
| 200 | 207 | ...repoHere(app, repo, viewer), |
| @@ -208,11 +215,23 @@ export function manifestFor( | ||
| 208 | 215 | }), |
| 209 | 216 | }, |
| 210 | 217 | you: youFor(viewer, scope, repo, app), |
| 211 | actions: repoActions(app, repo, viewer, scope), | |
| 218 | actions, | |
| 219 | can: canOf(actions), | |
| 212 | 220 | ...common, |
| 213 | 221 | }); |
| 214 | 222 | } |
| 215 | 223 | |
| 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 | ||
| 216 | 235 | function youFor( |
| 217 | 236 | viewer: User | undefined, |
| 218 | 237 | scope: TokenScope | undefined, |
src/crew/sandbox.ts +10 −6
| @@ -179,13 +179,17 @@ export function dataInTemp(data: string): boolean { | ||
| 179 | 179 | |
| 180 | 180 | function tempDenied(data: string, tmpDir: string | undefined): string[] { |
| 181 | 181 | 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 | } | |
| 182 | 190 | // 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]; | |
| 189 | 193 | } |
| 190 | 194 | |
| 191 | 195 | /** 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"; | ||
| 13 | 13 | import { quotaRefusal } from "../src/spawn/quota.ts"; |
| 14 | 14 | import { usePlacement, useProbe } from "../src/spawn/door.ts"; |
| 15 | 15 | import { hostedPlacement, memoryBodies } from "../src/spawn/placement.ts"; |
| 16 | import { SIZES } from "../src/spawn/sizes.ts"; | |
| 16 | 17 | import { quietLogs } from "./helpers/globals.ts"; |
| 17 | 18 | |
| 18 | 19 | quietLogs(); |
| @@ -101,7 +102,8 @@ describe("child quota", () => { | ||
| 101 | 102 | |
| 102 | 103 | test("room for small but not large is refused only for large", async () => { |
| 103 | 104 | 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); | |
| 105 | 107 | expect(quotaRefusal(dir, "small")).toBeUndefined(); |
| 106 | 108 | expect(quotaRefusal(dir, "large")).toContain("memory limit"); |
| 107 | 109 | }); |
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 | ||
| 314 | 314 | const { denyRead, tmpDir } = policy(); |
| 315 | 315 | expect(denied(join(dataDir, "crew/scout/01repo/7"), denyRead)).toBe(false); |
| 316 | 316 | 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)); | |
| 318 | 319 | expect(denied(tmpDir!, denyRead)).toBe(false); |
| 319 | 320 | }); |
| 320 | 321 |
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 | ||
| 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 | }); |
new above
offline
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.