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

/explore filters live in the URL: minimum forks, updated within, kind, with the same words in the explorer MCP tool #14133

Merged opened this

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

Merged

scout/forge:scout/14046-explore-filters-live-in-the-url-minimum → main 6 commits fork 3 threads · 3 unresolved

  • Merged. scout/14046-explore-filters-live-in-the-url-minimum was merged into main as a7eb4c3.

Review

Sign in to review this change.
11 files changed +133 −22
docs/MCP.md +1 −1
@@ -110,7 +110,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
110110 | `email_verify` | — | Send yourself a new verification link | 126 |
111111 | `estimate` | — | Ask an issue's base rate, or record `event` with `p50`, `p90` (instants) and `basis` | 406 |
112112 | `events` | — | Repository events | 259 |
113 | `explore` | — | The apps, people (and, for an admin, forges) you can see, ranked | 774 |
113 | `explore` | — | The apps, people (and, for an admin, forges) you can see, ranked | 804 |
114114 | `family` | — | The forge that sent this one and, for a site admin, those it sent, with state, version | 205 |
115115 | `features` | — | Apps absorbed as forge features: list, read, absorb or un-absorb, change typed settings | 357 |
116116 | `feed` | — | Your ranked home timeline; `cursor` pages; saved filter applies | 604 |
docs/features/explore.md +3
@@ -47,6 +47,7 @@ What a person filters on `/explore` an agent filters with the same words. Each f
4747 | Show archived | `archived=yes` | `?archived=yes` | `{ archived: "yes" }` |
4848 | (owner link on a row) | `owner=name` | `?owner=name` | `{ owner: "name" }` |
4949 | (type it) at least N forks by people | `forks=3` (0–1000) | `?forks=3` | `{ forks: "3" }` |
50 | (type it) the same floor, as shared links say it | `min_forks=3` (`forks=` wins when both are given); not a whole number from 0 to 1000 is `400` naming `min_forks`, on the page and the API | `?min_forks=3` | `{ min_forks: "3" }` |
5051 | (type it) at least N merges in 30 days | `ships=1` (0–1000) | `?ships=1` | `{ ships: "1" }` |
5152 | (type it) awake in the last 30 days | `live=yes` (`no` is no filter) | `?live=yes` | `{ live: "yes" }` |
5253 | Mine (signed in, beside the kind tabs) | `mine=yes` (`no` is no filter) | `?mine=yes` | `{ mine: "yes" }` |
@@ -54,6 +55,8 @@ What a person filters on `/explore` an agent filters with the same words. Each f
5455
5556 The one line still works everywhere: `?q=kind:app sort:forks garden` and `{ q: "kind:app sort:forks garden" }` read the same as the separate parameters, and old `/explore?q=…` links keep working. When a parameter and the same key in `q` are both given, the parameter wins (`?q=sort:name&sort=forks` sorts by forks). A parameter's value is one word; one the explorer does not take is an unknown word like any typed in `q`, and is refused the same way (below). The terminal's search line takes only the line. It takes `forks:N`, `ships:N` and `live:yes` there too (`screens/dashboard.ts` reads the line with `readExploreLine`): `forks:1 live:no` leaves the rows the page leaves, and `forks:abc` or `live:maybe` is named under `Read as:` as `forks:abc is not a count`, `live:maybe is not an answer`.
5657
58 A bad `min_forks`, `since`, `updated` or `kind` parameter (`?since=9y`, `?kind=nope`) is `400` naming the parameter, on the page and the API alike (#14046): the API answers `{ "error": "invalid", "field": "since", "message": "since is not a window — use 1d, 7d, 30d" }`, and the page still draws the same sentence over the unfiltered list. The sentence names the parameter and never repeats the value. `since` is judged only when `updated` is not given, `min_forks` only when `forks` is not.
59
5760 The three return the same ordered rows (`test/explore-parity.test.ts`; the URL form in `test/explore-url.test.ts`).
5861
5962 A `forks:` or `ships:` value that is not a whole number from 0 to 1000 (`abc`, `-1`, `1.5`, `1001`) and a `live:` that is not yes or no are unknown words like any other: `400` naming the word. Spawned forges carry no numbers, so any of the three leaves them out. The page's filter chips, `Drop` links and `Clear filters` carry the three words.
src/actions/explore.ts +26 −2
@@ -124,6 +124,30 @@ export function parseExploreQuery(line: string): ExploreQuery {
124124 */
125125 export const EXPLORE_PARAMS = ["kind", "sort", "updated", "owner", "archived", "forks", "ships", "live", "mine"] as const;
126126
127 /** A filter parameter refused at the boundary: the parameter and the sentence naming it. */
128 export interface ExploreRefusal {
129 readonly field: "min_forks" | "since" | "updated" | "kind";
130 readonly message: string;
131 }
132
133 /**
134 * The first bad `min_forks`, `updated`, `since` or `kind` parameter, else null. A parameter the
135 * line would not read (`min_forks` beside `forks`, `since` beside `updated`) is not judged. The
136 * sentence names the parameter, never echoes the value.
137 */
outdated

A bad min_forks (or since/kind) is folded into the line and reported only as a note on a 200. The boundary should answer 400 naming the parameter (min_forks), not forks.

138 export function badExploreParam(get: (name: string) => string | null | undefined): ExploreRefusal | null {
139 const given = (name: string) => (get(name) ?? "").trim();
140 const minForks = given("min_forks");
141 if (minForks !== "" && given("forks") === "" && countOf(minForks) === undefined)
142 return { field: "min_forks", message: `min_forks is not a count — use a whole number from 0 to ${COUNT_MAX}` };
143 const window = given("updated") !== "" ? "updated" : "since";
144 if (given(window) !== "" && !Object.hasOwn(WINDOWS, given(window).toLowerCase()))
145 return { field: window, message: `${window} is not a window — use ${Object.keys(WINDOWS).join(", ")}` };
146 if (given("kind") !== "" && !Object.hasOwn(KINDS, given("kind").toLowerCase()))
147 return { field: "kind", message: `kind is not a kind — use ${KIND_WORDS.join(", ")}` };
148 return null;
149 }
150
127151 /**
128152 * The one line a request asks for: `q`, then each separate parameter as its
129153 * `key:value` word. A value is one word (whitespace removed, so it cannot
@@ -133,8 +157,8 @@ export const EXPLORE_PARAMS = ["kind", "sort", "updated", "owner", "archived", "
133157 export function exploreLineFrom(get: (name: string) => string | null | undefined): string {
134158 const given = new Map<string, string>();
135159 for (const key of EXPLORE_PARAMS) {
136 // `since` is the same window as `updated`, in the words the chips are shared in.
137 const raw = get(key) || (key === "updated" ? get("since") : "") || "";
160 // `since` is the same window as `updated`, and `min_forks` the same floor as `forks`.
161 const raw = get(key) || (key === "updated" ? get("since") : key === "forks" ? get("min_forks") : "") || "";
138162 const value = raw.replace(/\s+/g, "").slice(0, 100);
139163 if (value !== "") given.set(key, value);
140164 }
src/http/api.ts +7 −3
@@ -363,6 +363,7 @@ import {
363363 exploreSuggestion,
364364 readExploreLine,
365365 exploreLineFrom,
366 badExploreParam,
366367 } from "../actions/explore.ts";
367368 import { frontInput, frontJson, setFront } from "../actions/front.ts";
368369 import { COPIES_PER_DAY, makeItYours } from "../actions/make_it_yours.ts";
@@ -3657,17 +3658,20 @@ export function apiRoutes(router: Router<Handler>): void {
36573658 // Explore (#607): the rows /explore shows, for the same one line.
36583659 router.add("GET", "/api/v1/explore", async (ctx) => {
36593660 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
3660 // The separate `sort`, `kind` and `limit` parameters are refused with 422
3661 // naming the field; a word typed in `q` keeps its 400 `unknown_filter`.
3661 // The separate `sort` and `limit` parameters are refused with 422 naming the
3662 // field; a bad `min_forks`, `since`, `updated` or `kind` with 400 naming it, as
3663 // the page does; a word typed in `q` keeps its 400 `unknown_filter`.
36623664 const limitRaw = ctx.url.searchParams.get("limit");
36633665 if (limitRaw !== null && !(/^\d{1,3}$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= 100))
36643666 return json({ error: "invalid", field: "limit", message: "limit is an integer from 1 to 100" }, 422);
36653667 const limit = limitRaw === null ? 30 : Number(limitRaw);
36663668 if (queryTooLong(ctx.url.searchParams.get("q")))
36673669 return json({ error: "invalid", field: "q", message: QUERY_TOO_LONG }, 422);
3670 const refused = badExploreParam((name) => ctx.url.searchParams.get(name));
3671 if (refused !== null) return json({ error: "invalid", field: refused.field, message: refused.message }, 400);
36683672 const line = exploreLineFrom((name) => ctx.url.searchParams.get(name));
36693673 const { query, unknown } = readExploreLine(line);
3670 for (const field of ["sort", "kind"] as const) {
3674 for (const field of ["sort"] as const) {
36713675 const given = ctx.url.searchParams.get(field);
36723676 if (given !== null && given.trim() !== "" && unknown.some((w) => w.toLowerCase().startsWith(`${field}:`)))
36733677 return json({ error: "invalid", field, message: exploreNote(unknown) }, 422);
src/http/mcp/tools/explore.ts +2 −1
@@ -4,7 +4,7 @@ import { exploreRun } from "../reads.ts";
44
55 export const tool: Tool = {
66 name: "explore",
7 doc: "`{ kind: tree, app }`: `{ app, upstream, forks, truncated }`, rows `{ repo, follows, standing, updatedAt }` for the app, the chain above it (nearest first) and its direct forks, in the words of the forks page, only what you may read, drawn on the `ui://forge/explore` card as upstream, this and fork rows; else `{ q?, cursor? }` (`query` is the same, `q` wins): the apps and people you can see, ranked, with `total` and `line` (how many the filter leaves, in the page's words) and, when filtered, `clear` (the call that drops it), with their numbers and `why` (a short line on the ranking, absent when none); `kind:` `sort:` `updated:` `owner:` `archived:` `forks:N` `ships:N` `live:yes` `mine:yes` (your own apps) and words in one line; each also as its own argument (`since` = `updated`); page on with `cursor`",
7 doc: "`{ kind: tree, app }`: `{ app, upstream, forks, truncated }`, rows `{ repo, follows, standing, updatedAt }` for the app, the chain above it (nearest first) and its direct forks, in the words of the forks page, only what you may read, drawn on the `ui://forge/explore` card as upstream, this and fork rows; else `{ q?, cursor? }` (`query` is the same, `q` wins): the apps and people you can see, ranked, with `total` and `line` (how many the filter leaves, in the page's words) and, when filtered, `clear` (the call that drops it), with their numbers and `why` (a short line on the ranking, absent when none); `kind:` `sort:` `updated:` `owner:` `archived:` `forks:N` `ships:N` `live:yes` `mine:yes` (your own apps) and words in one line; each also as its own argument (`since` = `updated`, `min_forks` = `forks`); page on with `cursor`",
88 description:
99 "The apps, people (and, for an admin, forges) you can see, ranked.",
1010 inputSchema: {
@@ -22,6 +22,7 @@ export const tool: Tool = {
2222 },
2323 ...Object.fromEntries(EXPLORE_PARAMS.map((k) => [k, { type: "string", maxLength: 100 }])),
2424 since: { type: "string", maxLength: 100 },
25 min_forks: { type: "string", maxLength: 100 },
2526 app: { type: "string", maxLength: 200, description: "With kind: tree" },
2627 cursor: {
2728 type: "string",
src/web/studio/explore.ts +10 −4
@@ -14,6 +14,7 @@ import {
1414 exploreCount,
1515 exploreFiltered,
1616 exploreLineFrom,
17 badExploreParam,
1718 exploreParams,
1819 exploreNote,
1920 exploreSuggestion,
@@ -183,7 +184,10 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
183184 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
184185 const line = exploreLineFrom((name) => ctx.url.searchParams.get(name));
185186 const { query, unknown } = readExploreLine(line);
186 const note = exploreNote(unknown);
187 // A bad `min_forks`, `since`, `updated` or `kind` is refused with 400 naming the parameter;
188 // a bad word typed in `q` (or another parameter) keeps its noted 200.
189 const refused = badExploreParam((name) => ctx.url.searchParams.get(name));
190 const note = refused?.message ?? exploreNote(unknown);
187191 const suggestion = exploreSuggestion(line);
188192 const ranking = performance.now();
189193 const shown = await explorePageAt(ctx.app, ctx.auth.user, query, explorePageFrom((name) => ctx.url.searchParams.get(name)));
@@ -304,8 +308,10 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
304308 extra: "bare",
305309 })}${pager(query, shown.page, shown.pages)}</div>`;
306310 const drawn = page({ ctx, title: "Explore", description: "Apps, forges and people on this forge, ranked by use, forks, ships and freshness.", body: compact(body), feed: { href: "/explore.atom", title: "Explore" } });
307 // An unknown filter is ignored with a plain note on the page (200); the API and the MCP stay
308 // strict.
311 // A refused parameter still draws the whole page, the unfiltered list under the note naming
312 // it, so a person who followed a bad link lands somewhere usable; only the status says 400.
313 // The same response is re-made with that status, keeping the drawn headers (security floor,
outdated

Only min_forks is refused with 400; a bad since or kind is still a noted 200 here. The issue asks for a 400 naming the parameter for every filter. Extend the refusal to since/updated/kind and update the #11819 test.

314 // CSP nonce) as they are.
309315 notePhase(ctx.request, "render", performance.now() - rendering);
310 return drawn;
316 return refused === null ? drawn : new Response(drawn.body, { status: 400, headers: drawn.headers });
311317 }
test/explore-api-paging.test.ts +5 −1
@@ -100,7 +100,11 @@ describe("refusals", () => {
100100 test("limit 101", () => refused("limit=101", "limit"));
101101 test("an empty limit", () => refused("limit=", "limit"));
102102 test("an unknown sort", () => refused("sort=bogus", "sort"));
103 test("an unknown kind", () => refused("kind=nope", "kind"));
103 test("an unknown kind is a 400 naming kind, as the page (#14046)", async () => {
104 const res = await get("kind=nope");
105 expect(res.status).toBe(400);
106 expect(((await res.json()) as { field: string }).field).toBe("kind");
107 });
104108 test("a cursor that is not one is still 400", async () => {
105109 expect((await get("cursor=%25%25")).status).toBe(400);
106110 });
test/explore-since.test.ts +2 −2
@@ -76,9 +76,9 @@ test("since=7d and since=30d keep exactly the apps changed inside the window", a
7676 expect(rows(await get("?kind=app&owner=pine&since=30d&sort=name"))).toEqual(["/pine/fresh", "/pine/stale"]);
7777 });
7878
79 test("an unknown since is ignored with a note, and the list is whole", async () => {
79 test("an unknown since is a 400 with a note, and the list is whole (#14046)", async () => {
8080 const res = await fetch(`${servers.url}/explore?kind=app&owner=pine&since=9y`);
81 expect(res.status).toBe(200);
81 expect(res.status).toBe(400);
8282 const html = await res.text();
8383 expect(rows(html).length).toBe(3);
8484 expect(html).toContain("1d, 7d, 30d");
test/explore-url-filters.test.ts +3 −3
@@ -95,11 +95,11 @@ test("a link with three filters renders the same rows as choosing them by hand",
9595 expect((await get("/explore?kind=app")).html).not.toContain(">Mine<");
9696 });
9797
98 test("an unknown filter value is ignored with a one-line note, never a 500", async () => {
98 test("an unknown filter value is ignored with a one-line note, never a 500 (a bad kind or since is a 400, #14046)", async () => {
9999 const plain = listed((await get("/explore", olive)).html);
100 for (const qs of ["?mine=maybe", "?kind=zzz", "?sort=zzz", "?since=9y"]) {
100 for (const [qs, status] of [["?mine=maybe", 200], ["?kind=zzz", 400], ["?sort=zzz", 200], ["?since=9y", 400]] as const) {
101101 const res = await get(`/explore${qs}`, olive);
102 expect(res.status).toBe(200);
102 expect(res.status).toBe(status);
103103 expect(res.html).toContain('role="status"');
104104 expect(listed(res.html)).toEqual(plain);
105105 }
test/explore-url.test.ts +47 −5
@@ -78,11 +78,13 @@ test("an unknown parameter is ignored; an invalid value is named and the default
7878 expect(listed(bad.html)).toEqual(listed(plain.html));
7979 });
8080
81 test("an unknown kind, sort or updated is a 200 with a plain note and the unfiltered list, escaped (#11819)", async () => {
81 // Was a 200 for every bad value (#11819); #14046 makes a bad kind, updated or since a 400 naming
82 // the parameter. The page under it is the same: the note and the unfiltered list, escaped.
83 test("an unknown sort is a 200, an unknown kind or updated a 400, each with a plain note and the unfiltered list, escaped (#11819, #14046)", async () => {
8284 const plain = listed((await page("")).html);
83 for (const qs of ["?kind=bogus", "?sort=bogus", "?updated=9y", "?since=9y", `?kind=${encodeURIComponent("<script>x</script>")}`]) {
85 for (const [qs, status] of [["?kind=bogus", 400], ["?sort=bogus", 200], ["?updated=9y", 400], ["?since=9y", 400], [`?kind=${encodeURIComponent("<script>x</script>")}`, 400]] as const) {
8486 const res = await page(qs);
85 expect(res.status).toBe(200);
87 expect(res.status).toBe(status);
8688 expect(res.html).toContain('role="status"');
8789 expect(res.html).toMatch(/is not a (kind|sort|window)/);
8890 expect(res.html).not.toContain("<script>x</script>");
@@ -104,13 +106,13 @@ test("the chips link with separate parameters", async () => {
104106 expect(exploreParams(readExploreLine("kind:app sort:forks owner:olive garden").query)).toBe("kind=app&sort=forks&owner=olive&q=garden");
105107 });
106108
107 test("`since` is the `updated` window: same line, bad value is a noted 200 (#11232)", async () => {
109 test("`since` is the `updated` window: same line, bad value is a noted 400 (#11232, #14046)", async () => {
108110 expect(exploreLineFrom((n) => (n === "since" ? "7d" : null))).toBe("updated:7d");
109111 expect(exploreLineFrom((n) => (n === "since" ? "9y" : null))).toBe("updated:9y");
110112 const ok = await fetch(`${servers.url}/explore?kind=app&since=7d`);
111113 expect(ok.status).toBe(200);
112114 const bad = await fetch(`${servers.url}/explore?since=9y`);
113 expect(bad.status).toBe(200);
115 expect(bad.status).toBe(400);
114116 expect(await bad.text()).toContain("1d, 7d, 30d");
115117 });
116118
@@ -159,3 +161,43 @@ test("active filters show as a chip row whose removes are links, escaped (#11819
159161 const hostile = await page(`?q=${encodeURIComponent('"><img src=x onerror=1>')}`);
160162 expect(hostile.html).not.toContain("<img src=x");
161163 });
164
165 test("since, updated and kind: a bad one is a 400 naming the parameter, on the page and the API (#14046)", async () => {
166 const plain = listed((await page("")).html);
167 for (const [qs, field, words] of [
168 ["since=9y", "since", "since is not a window"],
169 ["updated=forever", "updated", "updated is not a window"],
170 ["kind=nope", "kind", "kind is not a kind"],
171 ["kind=app&since=1y", "since", "since is not a window"],
172 ] as const) {
173 const res = await page(`?${qs}`);
174 expect(res.status).toBe(400);
175 expect(res.html).toContain(words);
176 // The bad parameter never narrows; a good one beside it still does.
177 expect(listed(res.html)).toEqual(qs.startsWith("kind=app&") ? listed((await page("?kind=app")).html) : plain);
178 const api = await fetch(`${servers.url}/api/v1/explore?${qs}`);
179 expect(api.status).toBe(400);
180 expect((await api.json()) as unknown).toMatchObject({ error: "invalid", field });
181 }
182 // A good value, any case, still narrows; `updated` wins over `since`, which is then not judged.
183 for (const qs of ["since=7d", "kind=APP", "updated=30d&since=nope"]) {
184 expect((await page(`?${qs}`)).status).toBe(200);
185 expect((await fetch(`${servers.url}/api/v1/explore?${qs}`)).status).toBe(200);
186 }
187 });
188
189 test("min_forks narrows the page and the API; a bad one is a 400 naming min_forks (#14046)", async () => {
190 const plain = listed((await page("")).html);
191 const ok = await page("?min_forks=1&kind=app");
192 expect(ok.status).toBe(200);
193 expect(listed(ok.html).length).toBeLessThan(plain.length);
194 for (const bad of ["abc", "-1", "1001"]) {
195 const res = await page(`?min_forks=${bad}`);
196 expect(res.status).toBe(400);
197 expect(res.html).toContain("min_forks is not a count");
198 const api = await fetch(`${servers.url}/api/v1/explore?min_forks=${bad}`);
199 expect(api.status).toBe(400);
200 expect(((await api.json()) as { field: string }).field).toBe("min_forks");
201 }
202 expect((await fetch(`${servers.url}/api/v1/explore?min_forks=0`)).status).toBe(200);
203 });
test/explorer-filters.test.ts added +27
@@ -0,0 +1,27 @@
1 /** `min_forks` is the floor `forks:` names, in the words the issue shares links in (#14046). */
2 import { expect, test } from "bun:test";
3 import { exploreLineFrom, readExploreLine } from "../src/actions/explore.ts";
4
5 const line = (p: Record<string, string>) => exploreLineFrom((n) => p[n]);
6
7 test("min_forks, since and kind each narrow the one line", () => {
8 expect(line({ min_forks: "3" })).toBe("forks:3");
9 expect(line({ since: "7d" })).toBe("updated:7d");
10 expect(line({ kind: "app" })).toBe("kind:app");
11 const q = readExploreLine(line({ min_forks: "3", since: "7d", kind: "app" })).query;
12 expect([q.forks, q.updated, q.kind]).toEqual([3, "7d", "app"]);
13 });
14
15 test("a bad value is named, left out, and never narrows", () => {

This checks only the parser. Add an HTTP-level test for the bad value that expects the 400 and the parameter name, and one for the good value.

16 for (const [k, v] of [["min_forks", "abc"], ["min_forks", "-1"], ["since", "9y"], ["kind", "nope"]] as const) {
17 const read = readExploreLine(line({ [k]: v }));
18 expect(read.unknown.length).toBe(1);
19 expect(read.query.forks).toBeUndefined();
20 expect(read.query.updated).toBe("all");
21 expect(read.query.kind).toBe("all");
22 }
23 });
24
25 test("forks wins over min_forks", () => {
26 expect(line({ forks: "2", min_forks: "5" })).toBe("forks:2");
27 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs