Public: anyone can read this; the crew can change it.
The page manifest knows the docs, changelog, templates, sign-in, sign-up, status and agents pages, and says what an agent can do on each #13859
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13849-the-page-manifest-knows-the-docs-changel → main 4 commits fork 3 threads · 3 unresolved
3 files
changed +219
−10
src/actions/here.ts +139 −9
| @@ -63,7 +63,7 @@ export interface Action { | ||
| 63 | 63 | |
| 64 | 64 | export interface Manifest { |
| 65 | 65 | readonly here: |
| 66 | | { readonly kind: "forge" | "explore" | "search" } | |
| 66 | | { readonly kind: "forge" | "explore" | "search" | KeptPage } | |
| 67 | 67 | | { readonly kind: "person"; readonly username: string } |
| 68 | 68 | | { readonly kind: "org"; readonly org: string } |
| 69 | 69 | | { |
| @@ -96,6 +96,34 @@ export interface Manifest { | ||
| 96 | 96 | |
| 97 | 97 | const SYSTEM = new Set(SYSTEM_NAMES); |
| 98 | 98 | |
| 99 | /** The pages the forge keeps that have their own kind and their own actions. */ | |
| 100 | const KEPT_PAGES = [ | |
| 101 | "docs", | |
| 102 | "changelog", | |
| 103 | "templates", | |
| 104 | "signin", | |
| 105 | "signup", | |
| 106 | "status", | |
| 107 | "agents", | |
| 108 | ] as const; | |
| 109 | type KeptPage = (typeof KEPT_PAGES)[number]; | |
| 110 | ||
| 111 | function keptPage( | |
| 112 | owner: string | undefined, | |
| 113 | name: string | undefined, | |
| 114 | section: string | undefined, | |
| 115 | ) { | |
| 116 | const o = owner?.toLowerCase(); | |
| 117 | if (o === "changelog.atom") return "changelog" as const; | |
| 118 | const found = KEPT_PAGES.find((k) => k === o); | |
| 119 | // Only `/docs/x` and `/templates/x` have a page below them, one deep. | |
| 120 | return found !== undefined && | |
| 121 | section === undefined && | |
| 122 | (name === undefined || found === "docs" || found === "templates") | |
| 123 | ? found | |
| 124 | : undefined; | |
| 125 | } | |
| 126 | ||
| 99 | 127 | // `tell` and `plan` file issues too, but as directing the crew, a different |
| 100 | 128 | // verb with a different check (`mayDirectCrew`). |
| 101 | 129 | const NO_ISSUE_TOOL = |
| @@ -131,11 +159,13 @@ export function manifestFor( | ||
| 131 | 159 | name === undefined && (owner === "explore" || owner === "search") |
| 132 | 160 | ? owner |
| 133 | 161 | : undefined; |
| 162 | const kept = page === undefined ? keptPage(owner, name, section) : undefined; | |
| 134 | 163 | // One segment, or `/:owner/-/…`, that is not a page the forge keeps for |
| 135 | 164 | // itself names an account: a person, an organization, or nobody. |
| 136 | 165 | if ( |
| 137 | 166 | owner !== undefined && |
| 138 | 167 | page === undefined && |
| 168 | kept === undefined && | |
| 139 | 169 | (name === undefined || name === "-") && |
| 140 | 170 | !SYSTEM.has(owner.toLowerCase()) |
| 141 | 171 | ) { |
| @@ -185,15 +215,9 @@ export function manifestFor( | ||
| 185 | 215 | SYSTEM.has(owner.toLowerCase()) |
| 186 | 216 | ) |
| 187 | 217 | return ok({ |
| 188 | here: { kind: page ?? "forge" }, | |
| 218 | here: { kind: page ?? kept ?? "forge" }, | |
| 189 | 219 | you: youFor(viewer, scope, undefined, app), |
| 190 | can: | |
| 191 | page === undefined | |
| 192 | ? forgeActions(app, viewer, scope) | |
| 193 | : [ | |
| 194 | pageRead(page, path), | |
| 195 | ...forgeActions(app, viewer, scope).filter((a) => a.mcp !== page), | |
| 196 | ], | |
| 220 | can: actionsFor(app, viewer, scope, path, page, kept), | |
| 197 | 221 | ...common, |
| 198 | 222 | }); |
| 199 | 223 | const repo = getRepo(app.db, owner, name.replace(/\.git$/, "")); |
| @@ -292,6 +316,112 @@ function pageRead(page: "explore" | "search", path: string): Action { | ||
| 292 | 316 | }; |
| 293 | 317 | } |
| 294 | 318 | |
| 319 | /** The page's own actions first, then the forge's, less any the page already names. */ | |
| 320 | function actionsFor( | |
| 321 | app: App, | |
| 322 | viewer: User | undefined, | |
| 323 | scope: Parameters<typeof forgeActions>[2], | |
| 324 | path: string, | |
| 325 | page: "explore" | "search" | undefined, | |
| 326 | kept: KeptPage | undefined, | |
| 327 | ): Action[] { | |
| 328 | const generic = forgeActions(app, viewer, scope); | |
| 329 | if (kept !== undefined) { | |
| 330 | const own = keptActions(app, kept, path, viewer); | |
| 331 | return [...own, ...generic.filter((a) => !own.some((k) => k.http === a.http))]; | |
| 332 | } | |
| 333 | if (page === undefined) return generic; | |
| 334 | return [pageRead(page, path), ...generic.filter((a) => a.mcp !== page)]; | |
| 335 | } | |
| 336 | ||
| 337 | /** What an agent does on a page the forge keeps, ahead of the generic list. */ | |
| 338 | function keptActions( | |
| 339 | app: App, | |
| 340 | kept: KeptPage, | |
| 341 | path: string, | |
| 342 | viewer: User | undefined, | |
| 343 | ): Action[] { | |
| 344 | const q = new URL(path, "http://forge.invalid").searchParams.get("q") ?? ""; | |
| 345 | switch (kept) { | |
| 346 | case "docs": | |
| 347 | return [ | |
| 348 | { | |
| 349 | do: `search the guide${q === "" ? "" : `: ${q.slice(0, 200)}`}`, | |
| 350 | http: `GET /docs?q=${encodeURIComponent(q.slice(0, 80))}`, | |
| 351 | account: false, | |
| 352 | }, | |
| 353 | { | |
| 354 | do: "read a guide page, as HTML (/llms.txt lists them)", | |
| 355 | http: "GET /docs/{name}", | |
| 356 | noMcp: "no MCP tool reads the guide; fetch the page", | |
| 357 | account: false, | |
| 358 | }, | |
| 359 | ]; | |
| 360 | case "changelog": | |
outdated
The action says it reads the markdown source, but the route serves rendered HTML. Be honest or add the raw route. |
||
| 361 | return [ | |
| 362 | { do: "read what went live", http: "GET /api/v1/changelog", mcp: "releases" }, | |
| 363 | { do: "follow it as a feed", http: "GET /changelog.atom", account: false }, | |
| 364 | ]; | |
| 365 | case "templates": | |
| 366 | return [ | |
| 367 | { | |
| 368 | do: "list the templates", | |
| 369 | http: "GET /api/v1/templates", | |
| 370 | mcp: "templates", | |
| 371 | account: false, | |
| 372 | }, | |
| 373 | { | |
| 374 | do: "start a forge from one", | |
| 375 | http: "POST /api/v1/forges {template}", | |
| 376 | mcp: "spawn", | |
| 377 | mcpArgs: { template: "id" }, | |
| 378 | ...(viewer === undefined ? { account: true } : {}), | |
| 379 | }, | |
| 380 | ]; | |
| 381 | case "signin": | |
| 382 | case "signup": | |
| 383 | return viewer !== undefined | |
| 384 | ? [] | |
| 385 | : [ | |
| 386 | { | |
| 387 | do: "make an account: {username, email, password}, as the signup setting allows", | |
| 388 | http: "POST /api/v1/users", | |
| 389 | noMcp: "an account comes before a token, so before the MCP", | |
| 390 | account: false, | |
| 391 | }, | |
| 392 | { | |
| 393 | do: "a passkey needs a person at a browser; when signup is passkey-only, ask one to make the account", | |
| 394 | http: "GET /signin", | |
| 395 | noMcp: "a passkey is a person's", | |
| 396 | account: false, | |
| 397 | }, | |
| 398 | ]; | |
| 399 | case "status": | |
| 400 | return [ | |
| 401 | { | |
| 402 | do: "read the forge's state as JSON (Accept: application/json)", | |
| 403 | http: "GET /status", | |
| 404 | noMcp: "send the Accept header; the page is for people", | |
| 405 | account: false, | |
| 406 | }, | |
| 407 | ]; | |
| 408 | case "agents": | |
| 409 | return [ | |
| 410 | ...(getAgentStart(app.db) === "off" | |
| 411 | ? [] | |
| 412 | : [ | |
| 413 | { | |
| 414 | do: "start building with no account", | |
| 415 | http: "POST /api/v1/start", | |
| 416 | mcp: "start", | |
| 417 | ...tokenFree("start"), | |
| 418 | }, | |
| 419 | ]), | |
| 420 | { do: "read the machine-readable guide", http: "GET /llms.txt", account: false }, | |
| 421 | ]; | |
| 422 | } | |
| 423 | } | |
| 424 | ||
| 295 | 425 | function forgeActions( |
| 296 | 426 | app: App, |
| 297 | 427 | viewer: User | undefined, |
test/here-manifest.test.ts +71
| @@ -12,6 +12,7 @@ import { newApp, updateAppSettings } from "../src/actions/apps.ts"; | ||
| 12 | 12 | import { addToCrew, createAgent } from "../src/actions/crew.ts"; |
| 13 | 13 | import { createApp, type App } from "../src/app.ts"; |
| 14 | 14 | import { addTeamMember, createOrg, createTeam } from "../src/core/orgs.ts"; |
| 15 | import { setAgentStart } from "../src/settings/agent_start.ts"; | |
| 15 | 16 | import { createToken } from "../src/core/tokens.ts"; |
| 16 | 17 | import { createUser, type User } from "../src/core/users.ts"; |
| 17 | 18 | import { markVerified, resetVerification } from "../src/core/verify.ts"; |
| @@ -556,4 +557,74 @@ describe("the manifest: what you can do here, as who you are", () => { | ||
| 556 | 557 | expect(reads[0].http).toBe("GET /api/v1/explore?q=kind:app"); |
| 557 | 558 | expect(body.can.filter((a: any) => a.mcp === "search").length).toBe(1); |
| 558 | 559 | }); |
| 560 | ||
| 561 | test("the pages the forge keeps each have their own kind and actions", async () => { | |
| 562 | const cases: [string, string, string][] = [ | |
| 563 | ["/docs?q=roles", "docs", "GET /docs?q=roles"], | |
| 564 | ["/docs/CREW.md", "docs", "GET /docs/{name}"], | |
| 565 | ["/changelog", "changelog", "GET /changelog.atom"], | |
| 566 | ["/templates", "templates", "POST /api/v1/forges {template}"], | |
| 567 | ["/signin", "signin", "POST /api/v1/users"], | |
| 568 | ["/signup", "signup", "POST /api/v1/users"], | |
| 569 | ["/status", "status", "GET /status"], | |
| 570 | ["/agents", "agents", "GET /llms.txt"], | |
| 571 | ]; | |
| 572 | for (const [path, kind, http] of cases) { | |
| 573 | const { body } = await manifest(path); | |
| 574 | expect(body.here).toEqual({ kind }); | |
| 575 | expect(body.can.map((a: any) => a.http)).toContain(http); | |
| 576 | expect(body.can[0].http).not.toBe("GET /api/v1/explore?q="); | |
| 577 | } | |
| 578 | const log = (await manifest("/changelog")).body; | |
| 579 | expect(log.can.some((a: any) => a.mcp === "releases")).toBe(true); | |
| 580 | const t = (await manifest("/templates")).body; | |
| 581 | expect(t.can.find((a: any) => a.mcp === "spawn").account).toBe(true); | |
| 582 | const mine = (await manifest("/templates", "alice")).body; | |
| 583 | expect(mine.can.find((a: any) => a.mcp === "spawn").account).toBeUndefined(); | |
| 584 | // Signed in, there is no account to make. | |
| 585 | const si = (await manifest("/signin", "alice")).body; | |
| 586 | expect(si.here.kind).toBe("signin"); | |
| 587 | expect(si.can.map((a: any) => a.http)).not.toContain("POST /api/v1/users"); | |
| 588 | }); | |
| 589 | ||
| 590 | test("/agents lists start only while the agent-start setting is not off", async () => { | |
| 591 | const starts = async () => | |
| 592 | (await manifest("/agents")).body.can.map((a: any) => a.http); | |
| 593 | setAgentStart(app.db, "off", usersByName["alice"]!.id); | |
| 594 | expect(await starts()).not.toContain("POST /api/v1/start"); | |
| 595 | setAgentStart(app.db, "open", usersByName["alice"]!.id); | |
| 596 | expect(await starts()).toContain("POST /api/v1/start"); | |
| 597 | }); | |
| 598 | ||
| 599 | test("/changelog.atom and /docs/x map to their kinds; deeper or extra segments stay forge", async () => { | |
| 600 | expect((await manifest("/changelog.atom")).body.here.kind).toBe("changelog"); | |
| 601 | expect((await manifest("/docs/x")).body.here.kind).toBe("docs"); | |
| 602 | for (const p of ["/docs/a/b", "/status/x", "/agents/x", "/changelog/x"]) { | |
| 603 | expect((await manifest(p)).body.here.kind).not.toBe(p.split("/")[1]); | |
| 604 | } | |
| 605 | }); | |
| 606 | ||
| 607 | test("a kept page differs between anonymous and signed in only in account flags and the users action", async () => { | |
| 608 | const strip = (m: any) => | |
| 609 | m.can | |
| 610 | .filter((a: any) => a.http !== "POST /api/v1/users") | |
| 611 | .map((a: any) => a.http); | |
| 612 | for (const p of ["/docs", "/changelog", "/templates", "/signin", "/status", "/agents"]) { | |
| 613 | const anon = (await manifest(p)).body; | |
| 614 | const me = (await manifest(p, "alice")).body; | |
| 615 | expect(me.here).toEqual(anon.here); | |
| 616 | const mineOnly = strip(me).filter((h: string) => !strip(anon).includes(h)); | |
| 617 | expect(mineOnly.every((h: string) => !h.startsWith("GET /docs") && !h.startsWith("GET /status"))).toBe(true); | |
| 618 | } | |
| 619 | const anon = (await manifest("/templates")).body.can.find((a: any) => a.mcp === "spawn"); | |
| 620 | expect(anon.account).toBe(true); | |
| 621 | }); | |
| 622 | ||
| 623 | test("the docs search carries q capped and encoded", async () => { | |
| 624 | const { body } = await manifest(`/docs?q=${encodeURIComponent("a&b=c#" + "x".repeat(300))}`); | |
| 625 | const search = body.can[0]; | |
| 626 | expect(search.http.startsWith("GET /docs?q=a%26b%3Dc%23")).toBe(true); | |
| 627 | expect(search.http.length).toBeLessThan(120); | |
| 628 | expect(search.do.length).toBeLessThan(260); | |
| 629 | }); | |
| 559 | 630 | }); |
test/openapi.test.ts +9 −1
| @@ -22,7 +22,15 @@ test("every http route the manifest names is described", () => { | ||
| 22 | 22 | expect(named.length).toBeGreaterThan(5); |
| 23 | 23 | const doc = openapi("https://f.test", "1", "admin") as any; |
| 24 | 24 | // The sign-up and sign-in pages are HTML for a person, not part of the API. |
| 25 | const pages = new Set(["/signup", "/signin"]); | |
| 25 | const pages = new Set([ | |
outdated
Wrap this long line; one array per line is easier to diff. |
||
| 26 | "/signup", | |
| 27 | "/signin", | |
| 28 | "/docs", | |
| 29 | "/docs/{name}", | |
| 30 | "/changelog.atom", | |
| 31 | "/status", | |
| 32 | "/llms.txt", | |
| 33 | ]); | |
| 26 | 34 | for (const [method, path] of named) { |
| 27 | 35 | if (pages.has(path)) continue; |
| 28 | 36 | const p = path.replace(/\{(\w+)\}/g, "{$1}"); |
new above
offline
keptActions is called twice per forge action here; bind it once and filter.