Public: anyone can read this; the crew can change it.
/explore narrows to the apps started from one template, by a plain link that survives a reload #14740
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14646-explore-narrows-to-the-apps-started-from → main 3 commits fork 2 threads · 2 unresolved
4 files
changed +130
−4
docs/features/explore.md +2
| @@ -75,6 +75,8 @@ One rule for what `/explore` does not take (#14392): an unknown sort, kind, filt | ||
| 75 | 75 | |
| 76 | 76 | `mine=yes` (or `mine:yes` in a line) keeps the viewer's own apps and the viewer's own person row: the owner is the viewer's name. Signed out it matches nothing, never everyone. Filters live in the URL, so `/explore?kind=app&mine=yes&sort=fresh` reloads and sends as the same view, and equals choosing Apps, Mine and Fresh by hand, row for row (`test/explore-url-filters.test.ts`). The terminal's search line takes `mine:yes` the same way (`mine:yes` after `/`): a guest sees no rows, the signed-in viewer sees their own (`test/tui-dashboard-explore.test.ts`). A `mine:` value other than yes or no is an unknown word like the others. |
| 77 | 77 | |
| 78 | `template=<name>` (or `template:<name>` in a line) keeps the forges whose spawn record names that template, a built-in id or `owner/name`: `/explore?template=trevato/shop`. It lists forges only, and only admins see forge rows, so anyone else gets an empty list worded "No forges to show for <name>". The value is checked against the template name shapes and matched by equality, never in SQL; one that is no template name is an unknown word, refused like the others. A chip `template:<name>` clears it. The terminal's search line takes `template:<id>` the same way (`readExploreLine`). Covered by `test/explore-template.test.ts`. | |
| 79 | ||
| 78 | 80 | ## Paging (#11376) |
| 79 | 81 | |
| 80 | 82 | A list holds 60 rows a page. When there are more, `/explore` ends with **Previous** and **Next** links around "Page N of M", plain links that keep kind, sort, since, owner, archived and the words and add `page=N` (page 1 has no `page`). `?page=2` is server-rendered and works without JavaScript. The page links say `rel="prev"` and `rel="next"`. An old `?cursor=` link shows the first page with one line saying the link is out of date. A `page` that is junk, zero or negative is a 303 to the first page, and one past the end to the last, each with its one-line note, never an error. `GET /api/v1/explore` returns `next_cursor` and takes `?cursor=`, and the MCP `explore` tool takes and returns the same cursor. |
src/actions/explore.ts +21 −3
| @@ -37,6 +37,7 @@ import { rankInputs } from "../core/rank_inputs.ts"; | ||
| 37 | 37 | import { writeStamp } from "../core/write_clock.ts"; |
| 38 | 38 | import { Stamped } from "../kernel/stamped.ts"; |
| 39 | 39 | import { listChildren } from "./spawn.ts"; |
| 40 | import { parseTemplate } from "../spawn/templates.ts"; | |
| 40 | 41 | import { described } from "../core/readme_description.ts"; |
| 41 | 42 | |
| 42 | 43 | export type ExploreKind = "app" | "person" | "forge"; |
| @@ -69,6 +70,11 @@ export interface ExploreQuery { | ||
| 69 | 70 | readonly live?: boolean; |
| 70 | 71 | /** `mine:yes` — only the viewer's own apps and the viewer; nothing when signed out. */ |
| 71 | 72 | readonly mine?: boolean; |
| 73 | /** | |
| 74 | * `template:<name>` — only forges whose spawn record names this template (a built-in id or | |
| 75 | * `owner/name`). | |
| 76 | */ | |
| 77 | readonly template?: string; | |
| 72 | 78 | } |
| 73 | 79 | |
| 74 | 80 | /** The most a `forks:` or `ships:` word may ask for. */ |
| @@ -122,7 +128,7 @@ export function parseExploreQuery(line: string): ExploreQuery { | ||
| 122 | 128 | /** |
| 123 | 129 | * The filter names a request may carry as separate parameters (`?kind=app&sort=forks`), beside `q`. |
| 124 | 130 | */ |
| 125 | export const EXPLORE_PARAMS = ["kind", "sort", "updated", "owner", "archived", "forks", "ships", "live", "mine"] as const; | |
| 131 | export const EXPLORE_PARAMS = ["kind", "sort", "updated", "owner", "archived", "forks", "ships", "live", "mine", "template"] as const; | |
| 126 | 132 | |
| 127 | 133 | /** A filter parameter refused at the boundary: the parameter and the sentence naming it. */ |
| 128 | 134 | export interface ExploreRefusal { |
| @@ -192,11 +198,12 @@ export function exploreParams(query: ExploreQuery): string { | ||
| 192 | 198 | if (query.ships !== undefined) p.set("ships", String(query.ships)); |
| 193 | 199 | if (query.live === true) p.set("live", "yes"); |
| 194 | 200 | if (query.mine === true) p.set("mine", "yes"); |
| 201 | if (query.template !== undefined) p.set("template", query.template); | |
| 195 | 202 | if (query.text !== "") p.set("q", query.text); |
| 196 | 203 | return p.toString(); |
| 197 | 204 | } |
| 198 | 205 | |
| 199 | const EXPLORE_KEYS = /(^|\s)(kind|sort|updated|owner|archived|forks|ships|live|mine):/i; | |
| 206 | const EXPLORE_KEYS = /(^|\s)(kind|sort|updated|owner|archived|forks|ships|live|mine|template):/i; | |
| 200 | 207 | |
| 201 | 208 | /** |
| 202 | 209 | * Whether a line has any word the explorer reads as a key, so every surface takes it as the |
| @@ -226,6 +233,7 @@ export function readExploreLine(line: string): ExploreRead { | ||
| 226 | 233 | let ships: number | undefined; |
| 227 | 234 | let live = false; |
| 228 | 235 | let mine = false; |
| 236 | let template: string | undefined; | |
| 229 | 237 | const words: string[] = []; |
| 230 | 238 | for (const word of line |
| 231 | 239 | .trim() |
| @@ -261,6 +269,9 @@ export function readExploreLine(line: string): ExploreRead { | ||
| 261 | 269 | } else if (k === "mine" && value !== "") { |
| 262 | 270 | if (["yes", "no"].includes(value.toLowerCase())) mine = value.toLowerCase() === "yes"; |
| 263 | 271 | else unknown.push(word); |
| 272 | } else if (k === "template" && value !== "") { | |
| 273 | if (parseTemplate(value).ok) template = value; | |
| 274 | else unknown.push(word); | |
| 264 | 275 | } else if (k === "q" && value !== "") words.push(value); |
| 265 | 276 | else words.push(word); |
| 266 | 277 | } |
| @@ -276,6 +287,7 @@ export function readExploreLine(line: string): ExploreRead { | ||
| 276 | 287 | ...(ships === undefined ? {} : { ships }), |
| 277 | 288 | ...(live ? { live } : {}), |
| 278 | 289 | ...(mine ? { mine } : {}), |
| 290 | ...(template === undefined ? {} : { template }), | |
| 279 | 291 | }, |
| 280 | 292 | unknown: unknown.slice(0, 5), |
| 281 | 293 | }; |
| @@ -296,6 +308,7 @@ export function exploreNote(unknown: readonly string[]): string { | ||
| 296 | 308 | if (key === "owner") return `${shown} is not a name`; |
| 297 | 309 | if (key === "updated") return `${shown} is not a window — use ${Object.keys(WINDOWS).join(", ")}`; |
| 298 | 310 | if (key === "archived" || key === "live" || key === "mine") return `${shown} is not an answer — use yes, no`; |
| 311 | if (key === "template") return `${shown} is not a template — use a template id or owner/name`; | |
| 299 | 312 | if (key === "forks" || key === "ships") return `${shown} is not a count — use a whole number from 0 to ${COUNT_MAX}`; |
| 300 | 313 | const sort = key === "sort"; |
| 301 | 314 | return `${shown} is not a ${sort ? "sort" : "kind"} — use ${(sort ? SORTS : KIND_WORDS).join(", ")}`; |
| @@ -374,6 +387,7 @@ export function exploreLine(query: ExploreQuery): string { | ||
| 374 | 387 | query.ships === undefined ? "" : `ships:${query.ships}`, |
| 375 | 388 | query.live === true ? "live:yes" : "", |
| 376 | 389 | query.mine === true ? "mine:yes" : "", |
| 390 | query.template === undefined ? "" : `template:${query.template}`, | |
| 377 | 391 | query.text, |
| 378 | 392 | ] |
| 379 | 393 | .filter((p) => p !== "") |
| @@ -588,6 +602,7 @@ export const exploreFiltered = (q: ExploreQuery): boolean => | ||
| 588 | 602 | q.ships !== undefined || |
| 589 | 603 | q.live === true || |
| 590 | 604 | q.mine === true || |
| 605 | q.template !== undefined || | |
| 591 | 606 | q.sort !== "score"; |
| 592 | 607 | |
| 593 | 608 | /** |
| @@ -762,6 +777,7 @@ async function everything( | ||
| 762 | 777 | ): Promise<{ readonly rows: readonly ExploreRow[]; readonly stamp: string | undefined }> { |
| 763 | 778 | const forgeRows = await forges(app, viewer, query); |
| 764 | 779 | const stamp = now === undefined ? writeStamp(app.db) : undefined; |
| 780 | if (query.template !== undefined) return { rows: place([], forgeRows, query), stamp }; | |
| 765 | 781 | if (stamp === undefined) return { rows: place(rank(app, viewer, query, now ?? Date.now()), forgeRows, query), stamp }; |
| 766 | 782 | let tiers = ranked.get(app.db); |
| 767 | 783 | if (tiers === undefined) { |
| @@ -786,7 +802,9 @@ async function forges(app: App, viewer: User | undefined, query: ExploreQuery): | ||
| 786 | 802 | // Nor does it carry forks, ships or a wake time, so a number asked for leaves it out. |
| 787 | 803 | if ((query.forks ?? 0) > 0 || (query.ships ?? 0) > 0 || query.live === true) return []; |
| 788 | 804 | if (viewer?.isAdmin !== true || (query.kind !== "all" && query.kind !== "forge")) return []; |
| 789 | return (await listChildren(app)).map((child) => ({ | |
| 805 | // The spawn record is the only place a template is kept: `template:` is matched against it by | |
| 806 | // equality, never in SQL, and an app or person has no record to match. | |
| 807 | return (await listChildren(app)).filter((c) => query.template === undefined || c.template === query.template).map((child) => ({ | |
| 790 | 808 | kind: "forge", |
| 791 | 809 | name: child.name, |
| 792 | 810 | url: child.url, |
src/web/studio/explore.ts +8 −1
| @@ -94,7 +94,7 @@ const shorten = (term: string): string => | ||
| 94 | 94 | term.length > 24 ? `${term.slice(0, 23)}…` : term; |
| 95 | 95 | |
| 96 | 96 | /** The query with one optional key left out. */ |
| 97 | function dropped(query: ExploreQuery, key: "forks" | "ships" | "live" | "owner" | "mine"): ExploreQuery { | |
| 97 | function dropped(query: ExploreQuery, key: "forks" | "ships" | "live" | "owner" | "mine" | "template"): ExploreQuery { | |
| 98 | 98 | const copy: Record<string, unknown> = { ...query }; |
| 99 | 99 | delete copy[key]; |
| 100 | 100 | return copy as unknown as ExploreQuery; |
| @@ -115,6 +115,7 @@ function terms(query: ExploreQuery): { term: string; without: ExploreQuery }[] { | ||
| 115 | 115 | if (query.ships !== undefined) out.push({ term: `ships:${query.ships}`, without: dropped(query, "ships") }); |
| 116 | 116 | if (query.live === true) out.push({ term: "live:yes", without: dropped(query, "live") }); |
| 117 | 117 | if (query.mine === true) out.push({ term: "mine:yes", without: dropped(query, "mine") }); |
| 118 | if (query.template !== undefined) out.push({ term: `template:${query.template}`, without: dropped(query, "template") }); | |
| 118 | 119 | const words = query.text.split(/\s+/).filter((w) => w !== ""); |
| 119 | 120 | words.forEach((word, i) => |
| 120 | 121 | out.push({ |
| @@ -128,6 +129,12 @@ function terms(query: ExploreQuery): { term: string; without: ExploreQuery }[] { | ||
| 128 | 129 | /** Nothing to list: a bare line means nothing is public yet, not a miss. */ |
| 129 | 130 | function emptyState(ctx: Ctx, query: ExploreQuery): Html { |
| 130 | 131 | const line = exploreLine(query); |
| 132 | if (query.template !== undefined) | |
| 133 | return empty({ | |
| 134 | icon: "search", | |
| 135 | title: `No forges to show for ${echoed(query.template)}`, | |
| 136 | note: "Only admins can list forges started from a template.", | |
| 137 | }); | |
| 131 | 138 | if (line !== "") |
| 132 | 139 | return empty({ |
| 133 | 140 | icon: "search", |
test/explore-template.test.ts added +99
| @@ -0,0 +1,99 @@ | ||
| 1 | /** | |
| 2 | * `/explore?template=<name>` narrows to the forges whose spawn record names that template, by a | |
| 3 | * plain link; the value is checked against the known template shapes and matched by equality | |
| 4 | * (#14646). | |
| 5 | */ | |
| 6 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 7 | import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; | |
| 8 | import { tmpdir } from "node:os"; | |
| 9 | import { join } from "node:path"; | |
| 10 | import { createApp, type App } from "../src/app.ts"; | |
| 11 | import { readExploreLine } from "../src/actions/explore.ts"; | |
| 12 | import { createSession } from "../src/core/sessions.ts"; | |
| 13 | import { createUser } from "../src/core/users.ts"; | |
| 14 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 15 | import { quietLogs } from "./helpers/globals.ts"; | |
| 16 | import { proveAll } from "./helpers/verified.ts"; | |
| 17 | import { seenFetch } from "./helpers/explore_seen.ts"; | |
| 18 | ||
| 19 | quietLogs(); | |
| 20 | let dir: string; | |
| 21 | let app: App; | |
| 22 | let servers: Servers; | |
| 23 | let admin = ""; | |
| 24 | let member = ""; | |
| 25 | ||
| 26 | beforeAll(async () => { | |
| 27 | dir = await mkdtemp(join(tmpdir(), "forge-explore-template-")); | |
| 28 | app = createApp({ dataDir: dir, port: 0 }); | |
| 29 | const made = await createUser(app.db, { origin: "seed", username: "olive", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 30 | if (!made.ok) throw new Error(made.error); | |
| 31 | const other = await createUser(app.db, { origin: "seed", username: "pine", email: "[email protected]", password: "a-good-passphrase" }); | |
| 32 | if (!other.ok) throw new Error(other.error); | |
| 33 | proveAll(app); | |
| 34 | member = `forge_session=${createSession(app.db, other.value.id).token}`; | |
| 35 | admin = `forge_session=${createSession(app.db, made.value.id).token}`; | |
| 36 | await mkdir(join(dir, "spawn"), { recursive: true }); | |
| 37 | for (const [name, template] of [["acme-shop", "trevato/shop"], ["acme-blog", "trevato/shop"], ["acme-docs", "trevato/docs"], ["acme-plain", undefined]] as const) | |
| 38 | await writeFile(join(dir, "spawn", `${name}.json`), JSON.stringify({ name, bodyId: `b-${name}`, done: true, ...(template === undefined ? {} : { template }) })); | |
| 39 | servers = await serve(app); | |
| 40 | }); | |
| 41 | afterAll(async () => { | |
| 42 | await servers.stop(); | |
| 43 | app.db.close(); | |
| 44 | await rm(dir, { recursive: true, force: true }); | |
outdated
|
||
| 45 | }); | |
| 46 | ||
| 47 | const get = async (path: string, cookie = admin) => { | |
| 48 | const res = await seenFetch(`${servers.url}${path}`, { headers: { cookie } }); | |
| 49 | return { status: res.status, html: await res.text() }; | |
| 50 | }; | |
| 51 | const has = (html: string, name: string) => new RegExp(`<a[^>]*>\\s*${name}\\s*</a>`).test(html); | |
| 52 | ||
| 53 | test("a known template lists only the forges started from it, with a link that clears it", async () => { | |
| 54 | const { status, html } = await get("/explore?template=trevato/shop"); | |
| 55 | expect(status).toBe(200); | |
| 56 | expect(has(html, "acme-shop")).toBe(true); | |
| 57 | expect(has(html, "acme-blog")).toBe(true); | |
| 58 | expect(has(html, "acme-docs")).toBe(false); | |
| 59 | expect(has(html, "acme-plain")).toBe(false); | |
| 60 | const chips = /data-filter-chips[\s\S]*?<\/div>/.exec(html)?.[0] ?? ""; | |
| 61 | expect(chips).toContain("template:trevato/shop"); | |
| 62 | expect(chips).toContain('href="/explore"'); | |
| 63 | }); | |
| 64 | ||
| 65 | test("it stacks with another filter, and clearing one keeps the other", async () => { | |
| 66 | const { html } = await get("/explore?template=trevato/shop&kind=forge&q=blog"); | |
| 67 | expect(has(html, "acme-blog")).toBe(true); | |
| 68 | expect(has(html, "acme-shop")).toBe(false); | |
| 69 | const chips = /data-filter-chips[\s\S]*?<\/div>/.exec(html)?.[0] ?? ""; | |
| 70 | expect(chips).toContain("kind:forge"); | |
| 71 | expect(chips).toMatch(/href="\/explore\?[^"]*kind=forge[^"]*"/); | |
| 72 | expect(chips).toMatch(/href="\/explore\?[^"]*template=trevato%2Fshop[^"]*"/); | |
| 73 | }); | |
| 74 | ||
| 75 | test("an unknown template shows an empty list in plain words", async () => { | |
| 76 | const { status, html } = await get("/explore?template=nobody/nothing"); | |
| 77 | expect(status).toBe(200); | |
| 78 | expect(html).toContain("No forges to show for nobody/nothing"); | |
| 79 | expect(html).not.toContain("acme-shop"); | |
| 80 | }); | |
| 81 | ||
| 82 | test("a value that is no template name is refused at the boundary, never used", async () => { | |
| 83 | expect(readExploreLine("template:x'; DROP TABLE repo;--").query.template).toBeUndefined(); | |
| 84 | expect(readExploreLine("template:trevato/shop").query.template).toBe("trevato/shop"); | |
| 85 | const { html } = await get("/explore?template=%27%3B%20DROP"); | |
| 86 | expect(html).toContain("is not a template"); | |
| 87 | expect(has(html, "acme-shop")).toBe(true); | |
| 88 | }); | |
| 89 | ||
| 90 | test("a non-admin and a guest never see forge rows, and are told so rather than that none exist", async () => { | |
| 91 | for (const cookie of [member, ""]) { | |
| 92 | const { status, html } = await get("/explore?template=trevato/shop", cookie); | |
| 93 | expect(status).toBe(200); | |
| 94 | expect(has(html, "acme-shop")).toBe(false); | |
| 95 | expect(html).toContain("No forges to show for trevato/shop"); | |
| 96 | expect(html).toContain("Only admins can list forges started from a template."); | |
| 97 | expect(html).not.toContain("No apps were started"); | |
| 98 | } | |
| 99 | }); |
new above
offline
Principle 8 / 1: 'No apps were started from X' is false for a non-admin (forge rows are hidden from them) and the note explains itself in two clauses. Give a plain sentence that is true for both viewers.