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

Merged opened this

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

Merged

scout/forge:scout/14646-explore-narrows-to-the-apps-started-from → main 3 commits fork 2 threads · 2 unresolved

  • Merged. scout/14646-explore-narrows-to-the-apps-started-from was merged into main as 404563e.

Review

Sign in to review this change.
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
7575
7676 `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.
7777
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
7880 ## Paging (#11376)
7981
8082 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";
3737 import { writeStamp } from "../core/write_clock.ts";
3838 import { Stamped } from "../kernel/stamped.ts";
3939 import { listChildren } from "./spawn.ts";
40 import { parseTemplate } from "../spawn/templates.ts";
4041 import { described } from "../core/readme_description.ts";
4142
4243 export type ExploreKind = "app" | "person" | "forge";
@@ -69,6 +70,11 @@ export interface ExploreQuery {
6970 readonly live?: boolean;
7071 /** `mine:yes` — only the viewer's own apps and the viewer; nothing when signed out. */
7172 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;
7278 }
7379
7480 /** The most a `forks:` or `ships:` word may ask for. */
@@ -122,7 +128,7 @@ export function parseExploreQuery(line: string): ExploreQuery {
122128 /**
123129 * The filter names a request may carry as separate parameters (`?kind=app&sort=forks`), beside `q`.
124130 */
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;
126132
127133 /** A filter parameter refused at the boundary: the parameter and the sentence naming it. */
128134 export interface ExploreRefusal {
@@ -192,11 +198,12 @@ export function exploreParams(query: ExploreQuery): string {
192198 if (query.ships !== undefined) p.set("ships", String(query.ships));
193199 if (query.live === true) p.set("live", "yes");
194200 if (query.mine === true) p.set("mine", "yes");
201 if (query.template !== undefined) p.set("template", query.template);
195202 if (query.text !== "") p.set("q", query.text);
196203 return p.toString();
197204 }
198205
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;
200207
201208 /**
202209 * 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 {
226233 let ships: number | undefined;
227234 let live = false;
228235 let mine = false;
236 let template: string | undefined;
229237 const words: string[] = [];
230238 for (const word of line
231239 .trim()
@@ -261,6 +269,9 @@ export function readExploreLine(line: string): ExploreRead {
261269 } else if (k === "mine" && value !== "") {
262270 if (["yes", "no"].includes(value.toLowerCase())) mine = value.toLowerCase() === "yes";
263271 else unknown.push(word);
272 } else if (k === "template" && value !== "") {
273 if (parseTemplate(value).ok) template = value;
274 else unknown.push(word);
264275 } else if (k === "q" && value !== "") words.push(value);
265276 else words.push(word);
266277 }
@@ -276,6 +287,7 @@ export function readExploreLine(line: string): ExploreRead {
276287 ...(ships === undefined ? {} : { ships }),
277288 ...(live ? { live } : {}),
278289 ...(mine ? { mine } : {}),
290 ...(template === undefined ? {} : { template }),
279291 },
280292 unknown: unknown.slice(0, 5),
281293 };
@@ -296,6 +308,7 @@ export function exploreNote(unknown: readonly string[]): string {
296308 if (key === "owner") return `${shown} is not a name`;
297309 if (key === "updated") return `${shown} is not a window — use ${Object.keys(WINDOWS).join(", ")}`;
298310 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`;
299312 if (key === "forks" || key === "ships") return `${shown} is not a count — use a whole number from 0 to ${COUNT_MAX}`;
300313 const sort = key === "sort";
301314 return `${shown} is not a ${sort ? "sort" : "kind"} — use ${(sort ? SORTS : KIND_WORDS).join(", ")}`;
@@ -374,6 +387,7 @@ export function exploreLine(query: ExploreQuery): string {
374387 query.ships === undefined ? "" : `ships:${query.ships}`,
375388 query.live === true ? "live:yes" : "",
376389 query.mine === true ? "mine:yes" : "",
390 query.template === undefined ? "" : `template:${query.template}`,
377391 query.text,
378392 ]
379393 .filter((p) => p !== "")
@@ -588,6 +602,7 @@ export const exploreFiltered = (q: ExploreQuery): boolean =>
588602 q.ships !== undefined ||
589603 q.live === true ||
590604 q.mine === true ||
605 q.template !== undefined ||
591606 q.sort !== "score";
592607
593608 /**
@@ -762,6 +777,7 @@ async function everything(
762777 ): Promise<{ readonly rows: readonly ExploreRow[]; readonly stamp: string | undefined }> {
763778 const forgeRows = await forges(app, viewer, query);
764779 const stamp = now === undefined ? writeStamp(app.db) : undefined;
780 if (query.template !== undefined) return { rows: place([], forgeRows, query), stamp };
765781 if (stamp === undefined) return { rows: place(rank(app, viewer, query, now ?? Date.now()), forgeRows, query), stamp };
766782 let tiers = ranked.get(app.db);
767783 if (tiers === undefined) {
@@ -786,7 +802,9 @@ async function forges(app: App, viewer: User | undefined, query: ExploreQuery):
786802 // Nor does it carry forks, ships or a wake time, so a number asked for leaves it out.
787803 if ((query.forks ?? 0) > 0 || (query.ships ?? 0) > 0 || query.live === true) return [];
788804 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) => ({
790808 kind: "forge",
791809 name: child.name,
792810 url: child.url,
src/web/studio/explore.ts +8 −1
@@ -94,7 +94,7 @@ const shorten = (term: string): string =>
9494 term.length > 24 ? `${term.slice(0, 23)}…` : term;
9595
9696 /** 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 {
9898 const copy: Record<string, unknown> = { ...query };
9999 delete copy[key];
100100 return copy as unknown as ExploreQuery;
@@ -115,6 +115,7 @@ function terms(query: ExploreQuery): { term: string; without: ExploreQuery }[] {
115115 if (query.ships !== undefined) out.push({ term: `ships:${query.ships}`, without: dropped(query, "ships") });
116116 if (query.live === true) out.push({ term: "live:yes", without: dropped(query, "live") });
117117 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") });
118119 const words = query.text.split(/\s+/).filter((w) => w !== "");
119120 words.forEach((word, i) =>
120121 out.push({
@@ -128,6 +129,12 @@ function terms(query: ExploreQuery): { term: string; without: ExploreQuery }[] {
128129 /** Nothing to list: a bare line means nothing is public yet, not a miss. */
129130 function emptyState(ctx: Ctx, query: ExploreQuery): Html {
130131 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)}`,
outdated

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.

136 note: "Only admins can list forges started from a template.",
137 });
131138 if (line !== "")
132139 return empty({
133140 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

has returns the same check in both branches of ||, so the first is dead. Match the row markup, and add a guest/non-admin case.

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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs