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

Explore narrows by forks, ships and a live app with three more words #12449

Merged opened this

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

Merged

scout/forge:scout/12414-explore-narrows-by-forks-ships-and-a-liv → main 4 commits fork

  • Merged. scout/12414-explore-narrows-by-forks-ships-and-a-liv was merged into main as d0db93a.

Review

Sign in to review this change.
9 files changed +176 −11
docs/MCP.md +1 −1
@@ -100,7 +100,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
100100 | `email_verify` | — | Send yourself a new verification link | 126 |
101101 | `estimate` | — | Ask an issue's base rate, or record `event` with `p50`, `p90` (instants) and `basis` | 406 |
102102 | `events` | — | Repository events | 259 |
103 | `explore` | — | The apps, people (and, for an admin, forges) you can see, ranked | 672 |
103 | `explore` | — | The apps, people (and, for an admin, forges) you can see, ranked | 749 |
104104 | `family` | — | The forge that sent this one and, for a site admin, those it sent, with state, version | 205 |
105105 | `features` | — | Apps absorbed as forge features: list, read, absorb or un-absorb, change typed settings | 357 |
106106 | `feed` | — | Your ranked home timeline; `cursor` pages; saved filter applies | 604 |
docs/features/explore.md +7 −2
@@ -1,6 +1,6 @@
11 # The explorer's sorts (#7753)
22
3 `/explore`, `GET /api/v1/explore`, the MCP tool `explore` and the terminal's search line (`/`, then a line with `kind:` or `sort:`) are one action, `explore` in `src/actions/explore.ts`. The line is `kind:app sort:likes updated:7d owner:name archived:yes words`.
3 `/explore`, `GET /api/v1/explore`, the MCP tool `explore` and the terminal's search line (`/`, then a line with `kind:` or `sort:`) are one action, `explore` in `src/actions/explore.ts`. The line is `kind:app sort:likes updated:7d owner:name archived:yes forks:3 ships:1 live:yes words`.
44
55 `sort:` takes one of:
66
@@ -41,12 +41,17 @@ What a person filters on `/explore` an agent filters with the same words. Each f
4141 | Any time / Today / This week / This month | `since=1d` `7d` `30d` (`updated=` is the same) | `?since=7d` | `{ since: "7d" }` |
4242 | Show archived | `archived=yes` | `?archived=yes` | `{ archived: "yes" }` |
4343 | (owner link on a row) | `owner=name` | `?owner=name` | `{ owner: "name" }` |
44 | (type it) at least N forks by people | `forks=3` (0–1000) | `?forks=3` | `{ forks: "3" }` |
45 | (type it) at least N merges in 30 days | `ships=1` (0–1000) | `?ships=1` | `{ ships: "1" }` |
46 | (type it) awake in the last 30 days | `live=yes` (`no` is no filter) | `?live=yes` | `{ live: "yes" }` |
4447 | the search box | `q=words` | `?q=words` | `{ q: "words" }` |
4548
46 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.
49 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`.
4750
4851 The three return the same ordered rows (`test/explore-parity.test.ts`; the URL form in `test/explore-url.test.ts`).
4952
53 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.
54
5055 An unknown filter word is refused the same way everywhere: `400` from the API (`{ "error": "unknown_filter", "message": "sort:bogus is not a sort — use score, forks, …", "suggest"? }`), an `unknown_filter` error from the MCP tool, and `400` on the page, which still draws the note, the did-you-mean link and the results. This replaces the earlier note-only answer (#7595).
5156
5257 ## Paging (#11376)
src/actions/explore.ts +55 −6
@@ -57,6 +57,21 @@ export interface ExploreQuery {
5757 readonly updated: ExploreWindow;
5858 /** `owner:<name>` — only this account's apps, and the person themself. */
5959 readonly owner?: string;
60 /** `forks:N` — at least this many forks by people. */
61 readonly forks?: number;
62 /** `ships:N` — at least this many merges in the signal window (30 days). */
63 readonly ships?: number;
64 /** `live:yes` — awake within the signal window (30 days). */
65 readonly live?: boolean;
66 }
67
68 /** The most a `forks:` or `ships:` word may ask for. */
69 const COUNT_MAX = 1000;
70 /** A whole number from 0 to COUNT_MAX, or undefined. */
71 function countOf(value: string): number | undefined {
72 if (!/^\d{1,4}$/.test(value)) return undefined;
73 const n = Number(value);
74 return n <= COUNT_MAX ? n : undefined;
6075 }
6176
6277 export type ExploreWindow = "all" | "1d" | "7d" | "30d";
@@ -98,7 +113,7 @@ export function parseExploreQuery(line: string): ExploreQuery {
98113 }
99114
100115 /** The filter names a request may carry as separate parameters (`?kind=app&sort=forks`), beside `q`. */
101 export const EXPLORE_PARAMS = ["kind", "sort", "updated", "owner", "archived"] as const;
116 export const EXPLORE_PARAMS = ["kind", "sort", "updated", "owner", "archived", "forks", "ships", "live"] as const;
102117
103118 /**
104119 * The one line a request asks for: `q`, then each separate parameter as its
@@ -130,11 +145,14 @@ export function exploreParams(query: ExploreQuery): string {
130145 if (query.updated !== "all") p.set("since", query.updated);
131146 if (query.archived) p.set("archived", "yes");
132147 if (query.owner !== undefined) p.set("owner", query.owner);
148 if (query.forks !== undefined) p.set("forks", String(query.forks));
149 if (query.ships !== undefined) p.set("ships", String(query.ships));
150 if (query.live === true) p.set("live", "yes");
133151 if (query.text !== "") p.set("q", query.text);
134152 return p.toString();
135153 }
136154
137 const EXPLORE_KEYS = /(^|\s)(kind|sort|updated|owner|archived):/i;
155 const EXPLORE_KEYS = /(^|\s)(kind|sort|updated|owner|archived|forks|ships|live):/i;
138156
139157 /** Whether a line has any word the explorer reads as a key, so every surface takes it as the explorer's. */
140158 export function isExploreLine(line: string): boolean {
@@ -154,6 +172,9 @@ export function readExploreLine(line: string): ExploreRead {
154172 let archived = false;
155173 let updated: ExploreWindow = "all";
156174 let owner: string | undefined;
175 let forks: number | undefined;
176 let ships: number | undefined;
177 let live = false;
157178 const words: string[] = [];
158179 for (const word of line
159180 .trim()
@@ -178,6 +199,14 @@ export function readExploreLine(line: string): ExploreRead {
178199 } else if (k === "owner" && value !== "") {
179200 if (isSafeName(value)) owner = value;
180201 else unknown.push(word);
202 } else if ((k === "forks" || k === "ships") && value !== "") {
203 const n = countOf(value);
204 if (n === undefined) unknown.push(word);
205 else if (k === "forks") forks = n;
206 else ships = n;
207 } else if (k === "live" && value !== "") {
208 if (["yes", "no"].includes(value.toLowerCase())) live = value.toLowerCase() === "yes";
209 else unknown.push(word);
181210 } else if (k === "q" && value !== "") words.push(value);
182211 else words.push(word);
183212 }
@@ -189,6 +218,9 @@ export function readExploreLine(line: string): ExploreRead {
189218 archived,
190219 updated,
191220 ...(owner === undefined ? {} : { owner }),
221 ...(forks === undefined ? {} : { forks }),
222 ...(ships === undefined ? {} : { ships }),
223 ...(live ? { live } : {}),
192224 },
193225 unknown: unknown.slice(0, 5),
194226 };
@@ -208,7 +240,8 @@ export function exploreNote(unknown: readonly string[]): string {
208240 const shown = word.length > 40 ? `${word.slice(0, 39)}…` : word;
209241 if (key === "owner") return `${shown} is not a name`;
210242 if (key === "updated") return `${shown} is not a window — use ${Object.keys(WINDOWS).join(", ")}`;
211 if (key === "archived") return `${shown} is not an answer — use yes, no`;
243 if (key === "archived" || key === "live") return `${shown} is not an answer — use yes, no`;
244 if (key === "forks" || key === "ships") return `${shown} is not a count — use a whole number from 0 to ${COUNT_MAX}`;
212245 const sort = key === "sort";
213246 return `${shown} is not a ${sort ? "sort" : "kind"} — use ${(sort ? SORTS : KIND_WORDS).join(", ")}`;
214247 })
@@ -232,7 +265,7 @@ function takenBy(key: string): readonly string[] {
232265 if (key === "kind") return Object.keys(KINDS);
233266 if (key === "sort") return SORTS;
234267 if (key === "updated") return Object.keys(WINDOWS);
235 if (key === "archived") return ["yes", "no"];
268 if (key === "archived" || key === "live") return ["yes", "no"];
236269 return [];
237270 }
238271
@@ -282,6 +315,9 @@ export function exploreLine(query: ExploreQuery): string {
282315 query.archived ? "archived:yes" : "",
283316 query.updated === "all" ? "" : `updated:${query.updated}`,
284317 query.owner === undefined ? "" : `owner:${query.owner}`,
318 query.forks === undefined ? "" : `forks:${query.forks}`,
319 query.ships === undefined ? "" : `ships:${query.ships}`,
320 query.live === true ? "live:yes" : "",
285321 query.text,
286322 ]
287323 .filter((p) => p !== "")
@@ -385,7 +421,14 @@ const NOUNS = {
385421
386422 /** True when the line narrows the list; the sort only orders it. */
387423 export const exploreFiltered = (q: ExploreQuery): boolean =>
388 q.kind !== "all" || q.text !== "" || q.archived || q.updated !== "all" || q.owner !== undefined;
424 q.kind !== "all" ||
425 q.text !== "" ||
426 q.archived ||
427 q.updated !== "all" ||
428 q.owner !== undefined ||
429 q.forks !== undefined ||
430 q.ships !== undefined ||
431 q.live === true;
389432
390433 /** How much a filter leaves, in words: "2 apps", "1 app", "No apps match". One sentence for the page and the terminal. */
391434 export function exploreCount(query: ExploreQuery, total: number): string {
@@ -529,7 +572,10 @@ async function everything(
529572 /** The forges this forge spawned, for a site admin asking for them. */
530573 async function forges(app: App, viewer: User | undefined, query: ExploreQuery): Promise<ExploreRow[]> {
531574 // A spawned forge carries no time, so a window leaves it out.
532 if (query.updated !== "all" || query.owner !== undefined || viewer?.isAdmin !== true || (query.kind !== "all" && query.kind !== "forge")) return [];
575 if (query.updated !== "all" || query.owner !== undefined) return [];
576 // Nor does it carry forks, ships or a wake time, so a number asked for leaves it out.
577 if ((query.forks ?? 0) > 0 || (query.ships ?? 0) > 0 || query.live === true) return [];
578 if (viewer?.isAdmin !== true || (query.kind !== "all" && query.kind !== "forge")) return [];
533579 return (await listChildren(app)).map((child) => ({
534580 kind: "forge",
535581 name: child.name,
@@ -670,6 +716,9 @@ function rank(
670716 (row) =>
671717 (query.kind === "all" || row.kind === query.kind) &&
672718 movedWithin(row, query, now) &&
719 (query.forks === undefined || row.numbers.forks >= query.forks) &&
720 (query.ships === undefined || row.numbers.ships >= query.ships) &&
721 (query.live !== true || row.numbers.awakeHours > 0) &&
673722 (only === undefined || (row.repo?.owner ?? row.name).toLowerCase() === only) &&
674723 (text === "" || `${row.name} ${row.description}`.toLowerCase().includes(text)),
675724 ),
src/http/mcp/tools/explore.ts +1 −1
@@ -4,7 +4,7 @@ import { bad, good, type Tool, str, repoArg, isAnswer } from "../shared.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:` 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` and words in one line; each also as its own argument (`since` = `updated`); page on with `cursor`",
88 description:
99 "The apps, people (and, for an admin, forges) you can see, ranked.",
1010 inputSchema: {
src/web/standards.ts +1 −1
@@ -511,7 +511,7 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
511511 ]),
512512 "## Find things (no account)",
513513 "",
514 `- Explore repositories: GET ${o}/api/v1/explore?q=kind:app+sort:forks+garden. (MCP "explore": with an account.) In q, kind: is app, person or forge; sort: is score, forks, ships, likes, use, fresh or name; updated: is 1d, 7d or 30d; owner:<name> is one account; archived: is yes or no; any other word is free text matched against name, owner and description.`,
514 `- Explore repositories: GET ${o}/api/v1/explore?q=kind:app+sort:forks+garden. (MCP "explore": with an account.) In q, kind: is app, person or forge; sort: is score, forks, ships, likes, use, fresh or name; updated: is 1d, 7d or 30d; owner:<name> is one account; archived: is yes or no; forks:N and ships:N are at least N (0-1000); live:yes is awake in 30 days; any other word is free text matched against name, owner and description.`,
515515 `- Search issues, pulls, repositories and code: GET ${o}/api/v1/search?q=websocket+timeout. (MCP "search": with an account.)`,
516516 "- Both read only what is public to you.",
517517 `- A pull's check as text: GET ${o}/{owner}/{name}/pulls/{number}/check.txt (pending, green or red; head: <oid>).`,
src/web/studio/explore.ts +10
@@ -96,6 +96,13 @@ function rowHtml(row: ExploreRow, signedIn: boolean, query: ExploreQuery, now: n
9696 const shorten = (term: string): string =>
9797 term.length > 24 ? `${term.slice(0, 23)}…` : term;
9898
99 /** The query with one optional key left out. */
100 function dropped(query: ExploreQuery, key: "forks" | "ships" | "live" | "owner"): ExploreQuery {
101 const copy: Record<string, unknown> = { ...query };
102 delete copy[key];
103 return copy as unknown as ExploreQuery;
104 }
105
99106 /** Each term of a missed line, with the query that is the line without it. */
100107 function terms(query: ExploreQuery): { term: string; without: ExploreQuery }[] {
101108 const out: { term: string; without: ExploreQuery }[] = [];
@@ -107,6 +114,9 @@ function terms(query: ExploreQuery): { term: string; without: ExploreQuery }[] {
107114 out.push({ term: "archived:yes", without: { ...query, archived: false } });
108115 if (query.updated !== "all")
109116 out.push({ term: `updated:${query.updated}`, without: { ...query, updated: "all" } });
117 if (query.forks !== undefined) out.push({ term: `forks:${query.forks}`, without: dropped(query, "forks") });
118 if (query.ships !== undefined) out.push({ term: `ships:${query.ships}`, without: dropped(query, "ships") });
119 if (query.live === true) out.push({ term: "live:yes", without: dropped(query, "live") });
110120 const words = query.text.split(/\s+/).filter((w) => w !== "");
111121 words.forEach((word, i) =>
112122 out.push({
test/explore-numbers.test.ts added +30
@@ -0,0 +1,30 @@
1 /** `forks:` `ships:` `live:` — one parser reads them, and refuses what is not a count (#12414). */
2 import { describe, expect, test } from "bun:test";
3 import { exploreFiltered, exploreLine, exploreNote, exploreParams, readExploreLine } from "../src/actions/explore.ts";
4
5 describe("the numeric words", () => {
6 test("each is read into the query and written back to the same line", () => {
7 const { query, unknown } = readExploreLine("forks:3 ships:1 live:yes garden");
8 expect(unknown).toEqual([]);
9 expect(query).toMatchObject({ forks: 3, ships: 1, live: true, text: "garden" });
10 expect(exploreLine(query)).toBe("forks:3 ships:1 live:yes garden");
11 expect(exploreParams(query)).toBe("forks=3&ships=1&live=yes&q=garden");
12 expect(exploreFiltered(query)).toBe(true);
13 });
14
15 test("zero and 1000 are counts; live:no is no filter", () => {
16 expect(readExploreLine("forks:0 ships:1000").unknown).toEqual([]);
17 const { query } = readExploreLine("live:no");
18 expect(query.live).toBeUndefined();
19 expect(exploreFiltered(query)).toBe(false);
20 });
21
22 test("a non-number, a negative, a fraction or a value over 1000 is unknown and named", () => {
23 for (const w of ["forks:abc", "ships:-2", "forks:1.5", "ships:1001", "forks:99999", "live:soon"]) {
24 const { unknown, query } = readExploreLine(w);
25 expect(unknown).toEqual([w]);
26 expect(query.forks ?? query.ships ?? query.live).toBeUndefined();
27 expect(exploreNote(unknown)).toContain(w);
28 }
29 });
30 });
test/explore-parity.test.ts +49
@@ -113,6 +113,10 @@ const LINES = [
113113 "owner:pine",
114114 "archived:yes",
115115 "kind:app sort:name garden",
116 "forks:1 kind:app",
117 "ships:2 kind:app",
118 "live:yes kind:app",
119 "forks:0 ships:1 live:yes",
116120 ];
117121
118122 /** The row links inside the page's `<ul class="list">`, in order: each row's title is the one link to its own url. */
@@ -160,6 +164,51 @@ describe("one filter, three surfaces", () => {
160164 });
161165 }
162166
167 const NARROWED: Record<string, string[]> = {
168 "kind:app forks:2": ["olive/loom-olive"],
169 "kind:app forks:1 sort:name": ["olive/garden-olive", "olive/loom-olive"],
170 "kind:app ships:2 sort:name": ["birch/loom-birch", "pine/garden-pine"],
171 "kind:app ships:1 sort:name": ["birch/loom-birch", "pine/garden-pine"],
172 "kind:app live:yes sort:name": ["birch/kiln-birch", "olive/garden-olive", "pine/kiln-pine"],
173 "kind:app live:no forks:3": [],
174 };
175 for (const [line, want] of Object.entries(NARROWED)) {
176 test(`"${line}" leaves exactly its rows on the API, the MCP and the page`, async () => {
177 const api = (await (await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent(line)}`)).json()) as { items: { kind: string; name: string; url: string }[] };
178 expect(api.items.map((i) => i.name)).toEqual(want);
179 const tool = await mcp(line);
180 expect(ids((JSON.parse(tool.text) as typeof api).items)).toEqual(ids(api.items));
181 const html = await (await fetch(`${servers.url}/explore?q=${encodeURIComponent(line)}`)).text();
182 expect(pageOrder(html)).toEqual(api.items.map((i) => i.url));
183 });
184 }
185
186 test("the new words are separate parameters too, and the page keeps them in Clear filters and the chips", async () => {
187 const qs = "kind=app&forks=1&ships=0&live=yes&sort=name";
188 const api = (await (await fetch(`${servers.url}/api/v1/explore?${qs}`)).json()) as { items: { name: string }[] };
189 expect(api.items.map((i) => i.name)).toEqual(["olive/garden-olive"]);
190 const html = await (await fetch(`${servers.url}/explore?${qs}`)).text();
191 expect(html).toContain("Remove filter forks:1");
192 expect(html).toContain("Remove filter live:yes");
193 expect(html).toContain("data-clear-filters");
194 });
195
196 test("a junk, negative or huge number is a 400 naming the word on the API, the MCP and the page", async () => {
197 for (const bad of ["forks:abc", "ships:-1", "forks:1001", "ships:1.5", "live:maybe"]) {
198 const api = await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent(bad)}`);
199 expect(api.status).toBe(400);
200 const body = (await api.json()) as { error: string; message: string };
201 expect(body.error).toBe("unknown_filter");
202 expect(body.message).toContain(bad);
203 const tool = await mcp(bad);
204 expect(tool.ok).toBe(false);
205 expect(tool.text).toContain(bad);
206 const page = await fetch(`${servers.url}/explore?q=${encodeURIComponent(bad)}`);
207 expect(await page.text()).toContain(bad);
208 }
209 expect((await fetch(`${servers.url}/api/v1/explore?q=forks:1000`)).status).toBe(200);
210 });
211
163212 test("the sorts are different orders, not one order under seven names", async () => {
164213 const seen = new Set<string>();
165214 for (const sort of ["score", "forks", "ships", "likes", "use", "fresh", "name"]) {
test/tui-dashboard-explore.test.ts +22
@@ -198,3 +198,25 @@ test("the terminal says how many a line leaves and that Esc clears it", async ()
198198 const none = await typed("kind:app zzzzqqq");
199199 expect(none).toContain("No apps match · Esc clears");
200200 });
201
202 test("forks:1 on the terminal's line leaves the rows the page's action leaves, and Read as carries the word", async () => {
203 const page = await explorePage(forge, alice, parseExploreQuery("kind:app forks:1 live:no"), null);
204 expect(page!.items.map((r) => r.name).sort()).toEqual(["alice/mid", "alice/zed"]);
205 const text = await typed("kind:app forks:1 live:no");
206 expect(text).toContain("Read as: kind:app forks:1 · 2 apps · Esc clears");
207 expect(text).toContain("alice/zed");
208 expect(text).toContain("alice/mid");
209 expect(text).not.toContain("alice/ant");
210 const none = await typed("kind:app forks:1 live:yes");
211 expect(none).toContain("forks:1 live:yes");
212 expect(none).toContain("No apps match");
213 expect(none).not.toContain("alice/zed");
214 });
215
216 test("forks:abc on the terminal is refused naming the word, as the page and the API refuse it", async () => {
217 const text = await typed("kind:app forks:abc");
218 expect(text).toContain("forks:abc is not a count");
219 expect(text).toContain("Read as: kind:app");
220 const answer = await typed("kind:app live:maybe");
221 expect(answer).toContain("live:maybe is not an answer");
222 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs