Public: anyone can read this; the crew can change it.
Each row on /explore says why it sits where it does in plain numbers: forks, ships, likes and age #13504
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/13483-each-row-on-explore-says-why-it-sits-whe → main 3 commits fork 2 threads · 2 unresolved
9 files
changed +144
−15
docs/features/explore.md +4
| @@ -20,6 +20,10 @@ The page's tabs are Best, Forks, Shipped, Liked, Use and Fresh; a row shows `N l | ||
| 20 | 20 | |
| 21 | 21 | Each row's meta line starts with one phrase for the signal that most explains its place: `12 forks`, `3 shipped this month`, `2 likes`, `shipped today`, `in use`. On a named sort it is that sort's signal; on `score` it is the largest term of the score, weighed as the ranking weighs them (`frontScore` at the forge's front weights, and `LIKE_WEIGHT` for likes; a tie goes to forks, ships, likes, freshness, use). `whyOf` in `actions/explore.ts` reads it from the row's numbers, with no query. The number the phrase says is left out of the rest of the line, so nothing is said twice. The terminal's explorer lines (`/` then `kind:` or `sort:`) show the same phrase first and drop the same duplicate. A row with nothing to say has no phrase; `sort:name` has none. |
| 22 | 22 | |
| 23 | ## The figures line on an app row (#13483) | |
| 24 | ||
| 25 | An app's meta line opens with its numbers in full: `3 forks, 5 ships, 2 likes, shipped 2d ago · description`. Forks and ships are always said, even at zero; likes appear when there are some, or when the sort is `likes`; `sort:use` adds `N h in use`. So the figure the active sort ranks by is always on the line. The age is `shipped <time>` on the page (the exact date is the `<time>` element's title), `never shipped` when there is none. The meta stays one ellipsised line at 360 px (`.row-meta`, asserted in `test/explorer-why.test.ts`). `GET /api/v1/explore` and the MCP `explore` tool carry the same line as `figures` on each app row (the age worded by `shippedWords`: `shipped 2 days ago`), `figuresOf` in `actions/explore.ts`; the terminal's explorer rows say it too. People and forges have no `figures`; they keep the `why` phrase. | |
| 26 | ||
| 23 | 27 | ## How likes count |
| 24 | 28 | |
| 25 | 29 | A like is a `feed_like` row (one per person and post, `src/feed/likes.ts`). An app's count is the likes on posts about its repository, read only for repositories the viewer may read: a private app's likes are never in a public row, and a stranger never sees the private app at all. A person's count is the sum over the apps shown to the viewer. |
src/actions/explore.ts +31 −2
| @@ -355,6 +355,33 @@ function shippedWords(shippedAt: string | null, now: number): string { | ||
| 355 | 355 | return `shipped ${days} days ago`; |
| 356 | 356 | } |
| 357 | 357 | |
| 358 | /** | |
| 359 | * The counts of an app row's line, said in full ("3 forks, 5 ships, 2 likes"): forks and ships | |
| 360 | * always, likes when there are some or the sort ranks by them, hours awake when the sort ranks by | |
| 361 | * use. Whatever the active sort ranks by is always on the line, even at zero. Empty for a row that | |
| 362 | * is not an app. | |
| 363 | */ | |
| 364 | export function figureCounts(row: ExploreRow, sort: ExploreSort = "score"): string { | |
| 365 | if (row.kind !== "app") return ""; | |
| 366 | const n = row.numbers; | |
| 367 | return [ | |
| 368 | plural(n.forks, "fork", "forks"), | |
| 369 | plural(n.ships, "ship", "ships"), | |
| 370 | n.likes > 0 || sort === "likes" ? plural(n.likes, "like", "likes") : "", | |
| 371 | sort === "use" ? `${n.awakeHours} h in use` : "", | |
| 372 | ] | |
| 373 | .filter((p) => p !== "") | |
| 374 | .join(", "); | |
| 375 | } | |
| 376 | ||
| 377 | /** | |
| 378 | * The whole line for the API and the terminal: the counts, then the age as `shippedWords` says it. | |
| 379 | */ | |
| 380 | export function figuresOf(row: ExploreRow, now: number, sort: ExploreSort = "score"): string { | |
| 381 | const counts = figureCounts(row, sort); | |
| 382 | return counts === "" ? "" : `${counts}, ${shippedWords(row.shippedAt, now) || "never shipped"}`; | |
| 383 | } | |
| 384 | ||
| 358 | 385 | /** The signals a row can rank by; a row line that says one need not say it twice. */ |
| 359 | 386 | export type WhySignal = "forks" | "ships" | "likes" | "fresh" | "use"; |
| 360 | 387 | |
| @@ -501,12 +528,14 @@ export async function explore( | ||
| 501 | 528 | * The rows as the API and the MCP send them: each with its `why` line when the ranking has one to |
| 502 | 529 | * say (omitted otherwise). |
| 503 | 530 | */ |
| 504 | export function rowsWithWhy(app: App, query: ExploreQuery, items: readonly ExploreRow[]): (ExploreRow & { why?: string })[] { | |
| 531 | export function rowsWithWhy(app: App, query: ExploreQuery, items: readonly ExploreRow[]): (ExploreRow & { why?: string; figures?: string })[] { | |
| 505 | 532 | const weights = frontWeights(app.db); |
| 506 | 533 | const now = Date.now(); |
| 507 | 534 | return items.map((row) => { |
| 508 | 535 | const why = whyOf(row, query.sort, now, weights); |
| 509 | return why === undefined ? row : { ...row, why: why.text }; | |
| 536 | const figures = figuresOf(row, now, query.sort); | |
| 537 | const out = figures === "" ? row : { ...row, figures }; | |
| 538 | return why === undefined ? out : { ...out, why: why.text }; | |
| 510 | 539 | }); |
| 511 | 540 | } |
| 512 | 541 |
src/tui/screens/dashboard.ts +4 −1
| @@ -15,7 +15,7 @@ | ||
| 15 | 15 | */ |
| 16 | 16 | |
| 17 | 17 | import { DEFAULT_WEIGHTS, frontWeights, type FrontWeights } from "../../core/front.ts"; |
| 18 | import { exploreCount, exploreFiltered, exploreLine, isExploreLine, exploreNote, exploreSuggestion, explorePage, parseExploreQuery, readExploreLine, whyOf, type ExploreRow } from "../../actions/explore.ts"; | |
| 18 | import { exploreCount, exploreFiltered, exploreLine, isExploreLine, exploreNote, exploreSuggestion, explorePage, parseExploreQuery, readExploreLine, whyOf, figuresOf, type ExploreRow } from "../../actions/explore.ts"; | |
| 19 | 19 | import { protectionNotice } from "../../kernel/protection.ts"; |
| 20 | 20 | import { holdWords, plannerHold } from "../../crew/autonomy.ts"; |
| 21 | 21 | import { governorLine, governorSeen } from "../../crew/governed.ts"; |
| @@ -1624,6 +1624,9 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen { | ||
| 1624 | 1624 | // The row's reason first, as the page says it; its numbers are not said again. |
| 1625 | 1625 | const why = whyOf(row, parseExploreQuery(explored?.line ?? "").sort, Date.now(), exploredWeights); |
| 1626 | 1626 | const said = why?.signal; |
| 1627 | // An app says the page's figures line, as the page does; the rest is for people and forges. | |
| 1628 | const figures = figuresOf(row, Date.now(), parseExploreQuery(explored?.line ?? "").sort); | |
| 1629 | if (figures !== "") return figures; | |
| 1627 | 1630 | return metaOf( |
| 1628 | 1631 | why?.text ?? "", |
| 1629 | 1632 | row.kind === "person" ? plural(n.apps, "app") : "", |
src/web/studio/explore.ts +5 −2
| @@ -17,6 +17,7 @@ import { | ||
| 17 | 17 | exploreSuggestion, |
| 18 | 18 | MAKE_IT_YOURS, |
| 19 | 19 | whyOf, |
| 20 | figureCounts, | |
| 20 | 21 | readExploreLine, |
| 21 | 22 | type ExploreQuery, |
| 22 | 23 | type ExploreRow, |
| @@ -39,12 +40,14 @@ const href = (query: ExploreQuery): string => { | ||
| 39 | 40 | function rowHtml(row: ExploreRow, signedIn: boolean, query: ExploreQuery, now: number, weights: FrontWeights): Html { |
| 40 | 41 | const why = whyOf(row, query.sort, now, weights); |
| 41 | 42 | // One row: what it does in plain words, then the one signal that explains its place. |
| 42 | const signal = why === undefined ? "" : why.signal === "fresh" && row.shippedAt !== null ? html`shipped ${time(row.shippedAt)}` : html`${why.text}`; | |
| 43 | // Apps say their counts and keep the dated `<time>`: the absolute date stays in its title. | |
| 44 | const figures = figureCounts(row, query.sort); | |
outdated
The line replaces the |
||
| 45 | const signal = figures !== "" ? (row.shippedAt === null ? html`${figures}, never shipped` : html`${figures}, shipped ${time(row.shippedAt)}`) : why === undefined ? "" : why.signal === "fresh" && row.shippedAt !== null ? html`shipped ${time(row.shippedAt)}` : html`${why.text}`; | |
| 43 | 46 | // One tap from a person to their apps; with none, the count is plain text. |
| 44 | 47 | const theirs = href({ kind: "app", sort: "score", text: "", archived: false, updated: "all", owner: row.name }); |
| 45 | 48 | const apps = row.kind === "person" ? `${row.numbers.apps} app${row.numbers.apps === 1 ? "" : "s"}` : ""; |
| 46 | 49 | const count = apps === "" ? html`` : row.numbers.apps > 0 ? html`<a href="${theirs}">${apps}</a>` : html`${apps}`; |
| 47 | const parts = [row.description === "" ? html`` : html`${row.description}`, signal === "" ? html`` : html`${signal}`, count].filter((p) => p.toString() !== ""); | |
| 50 | const parts = [signal === "" ? html`` : html`${signal}`, row.description === "" ? html`` : html`${row.description}`, count].filter((p) => p.toString() !== ""); | |
| 48 | 51 | const metaHtml = parts.reduce((all, p, i) => (i === 0 ? p : html`${all} · ${p}`), html``); |
| 49 | 52 | return rowOf({ |
| 50 | 53 | title: html`<a href="${row.url}">${row.name}</a>${nameMark(row.mark)}`, |
test/explore-first-view.test.ts +3 −3
| @@ -62,7 +62,7 @@ describe("/explore first view", () => { | ||
| 62 | 62 | const from = html.indexOf('class="list"'); |
| 63 | 63 | const list = html.slice(from, html.indexOf("</ul>", from)); |
| 64 | 64 | expect((list.match(/class="row"/g) ?? []).length).toBe(12); |
| 65 | expect(list.length / 12).toBeLessThan(500); | |
| 65 | expect(list.length / 12).toBeLessThan(520); // the figures line adds ~35 bytes a row (#13483) | |
| 66 | 66 | }); |
| 67 | 67 | |
| 68 | 68 | test("the rows come in the ranking's order", () => { |
| @@ -75,8 +75,8 @@ describe("/explore first view", () => { | ||
| 75 | 75 | expect(html).toContain("Does thing number 0 in plain words"); |
| 76 | 76 | // A row's meta is `description · signal`, one signal and no more. |
| 77 | 77 | const meta = [...html.matchAll(/class="row-meta">([^<]*)</g)].map((m) => m[1]); |
| 78 | expect(meta).toContain("Does thing number 0 in plain words · 1 fork"); | |
| 79 | expect(meta).toContain("Does thing number 1 in plain words"); | |
| 78 | expect(meta).toContain("1 fork, 0 ships, never shipped · Does thing number 0 in plain words"); | |
| 79 | expect(meta.some((m) => m!.endsWith("· Does thing number 1 in plain words"))).toBe(true); | |
| 80 | 80 | for (const m of meta) expect(m!.split(" · ").length).toBeLessThanOrEqual(2); |
| 81 | 81 | // Sort, time and archived sit behind one disclosure, closed on the bare view. |
| 82 | 82 | expect(html).toMatch(/<details class="mb small" data-more-filters>/); |
test/explore-parity.test.ts +17 −6
| @@ -1,4 +1,7 @@ | ||
| 1 | /** One filter, one word: the page, the API and the MCP `explore` tool return the same ordered ids (#10387). */ | |
| 1 | /** | |
| 2 | * One filter, one word: the page, the API and the MCP `explore` tool return the same ordered ids | |
| 3 | * (#10387). | |
| 4 | */ | |
| 2 | 5 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 3 | 6 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 7 | import { tmpdir } from "node:os"; |
| @@ -51,7 +54,10 @@ afterAll(async () => { | ||
| 51 | 54 | |
| 52 | 55 | const DAY = 86_400_000; |
| 53 | 56 | |
| 54 | /** Signals that make every sort a different order: who is forked, shipped, liked, awake, fresh, and archived. */ | |
| 57 | /** | |
| 58 | * Signals that make every sort a different order: who is forked, shipped, liked, awake, fresh, and | |
| 59 | * archived. | |
| 60 | */ | |
| 55 | 61 | function seedSignals(): void { |
| 56 | 62 | const repoId = (owner: string, name: string): string => { |
| 57 | 63 | const row = app.db.query<{ id: string }, [string, string]>("SELECT repo.id AS id FROM repo JOIN user ON user.id = repo.owner_id WHERE user.username = ?1 AND repo.name = ?2").get(owner, name); |
| @@ -66,7 +72,8 @@ function seedSignals(): void { | ||
| 66 | 72 | fork(["pine", "kiln-pine"], ["olive", "loom-olive"]); |
| 67 | 73 | fork(["pine", "garden-pine"], ["olive", "loom-olive"]); |
| 68 | 74 | fork(["birch", "kiln-birch"], ["olive", "garden-olive"]); |
| 69 | // ships (merged pulls): garden-pine 3 (latest 5d ago), loom-birch 2 (latest 1d ago), kiln-olive 1 (45d ago, outside the window) | |
| 75 | // ships (merged pulls): garden-pine 3 (latest 5d ago), loom-birch 2 (latest 1d ago), kiln-olive 1 | |
| 76 | // (45d ago, outside the window) | |
| 70 | 77 | const ship = (r: [string, string], ago: number) => { |
| 71 | 78 | const issue = createIssue(app.db, { repoId: repoId(...r), authorId: owner, title: "change", kind: "pull" }); |
| 72 | 79 | if (!issue.ok) throw new Error(issue.error); |
| @@ -119,7 +126,10 @@ const LINES = [ | ||
| 119 | 126 | "forks:0 ships:1 live:yes", |
| 120 | 127 | ]; |
| 121 | 128 | |
| 122 | /** The row links inside the page's `<ul class="list">`, in order: each row's title is the one link to its own url. */ | |
| 129 | /** | |
| 130 | * The row links inside the page's `<ul class="list">`, in order: each row's title is the one link | |
| 131 | * to its own url. | |
| 132 | */ | |
| 123 | 133 | function pageOrder(html: string): string[] { |
| 124 | 134 | const list = /<ul class="list">([\s\S]*?)<\/ul>/.exec(html); |
| 125 | 135 | if (list === null) return []; |
| @@ -139,7 +149,8 @@ async function mcp(line: string): Promise<{ ok: boolean; text: string }> { | ||
| 139 | 149 | } |
| 140 | 150 | |
| 141 | 151 | describe("one filter, three surfaces", () => { |
| 142 | // The orders the seeded signals must give, so a sort that ignores its signal (and falls back to name) fails. | |
| 152 | // The orders the seeded signals must give, so a sort that ignores its signal (and falls back to | |
| 153 | // name) fails. | |
| 143 | 154 | const EXPECTED: Record<string, string[]> = { |
| 144 | 155 | "kind:app sort:forks": ["olive/loom-olive", "olive/garden-olive"], |
| 145 | 156 | "kind:app sort:ships": ["pine/garden-pine", "birch/loom-birch"], |
| @@ -312,7 +323,7 @@ describe("separate parameters", () => { | ||
| 312 | 323 | }); |
| 313 | 324 | |
| 314 | 325 | describe("last ship on the row", () => { |
| 315 | test("the page words it as 'shipped 1d ago' with the absolute date in title; the API carries shippedAt", async () => { | |
| 326 | test("the page words it as shipped 1d ago with the absolute date in title; the API carries shippedAt", async () => { | |
| 316 | 327 | const html = await (await fetch(`${servers.url}/explore?q=${encodeURIComponent("kind:app sort:fresh")}`)).text(); |
| 317 | 328 | expect(html).toMatch(/shipped <time datetime="[^"]+" title="\d{4}-\d\d-\d\d \d\d:\d\d UTC"\s*>1d ago<\/time/); |
| 318 | 329 | const api = (await (await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent("kind:app sort:fresh")}`)).json()) as { items: { name: string; shippedAt: string | null }[] }; |
test/explore.test.ts +1 −1
| @@ -237,7 +237,7 @@ describe("explore", () => { | ||
| 237 | 237 | const page = await (await fetch(`${base}/explore?q=${encodeURIComponent("kind:app sort:ships")}`)).text(); |
| 238 | 238 | expect(page).toContain('value="kind:app sort:ships"'); |
| 239 | 239 | expect(page.indexOf('href="/bob/busy"')).toBeLessThan(page.indexOf('href="/alice/loved"')); |
| 240 | expect(page).toContain("shipped this month"); | |
| 240 | expect(page).toContain("0 forks, 3 ships, shipped <time datetime="); // the sort's own figure, with the dated time | |
| 241 | 241 | expect(page).not.toContain("data-why"); |
| 242 | 242 | expect(page).toContain("Make it yours"); |
| 243 | 243 | expect(page).not.toContain("alice/secret"); |
test/explorer-why.test.ts added +70
| @@ -0,0 +1,70 @@ | ||
| 1 | /** | |
| 2 | * Each explorer app row says its figures in one escaped line, and the API says the same (#13483). | |
| 3 | */ | |
| 4 | import { expect, test } from "bun:test"; | |
| 5 | import { figuresOf, rowsWithWhy, type ExploreRow } from "../src/actions/explore.ts"; | |
| 6 | import { createApp } from "../src/app.ts"; | |
| 7 | import { mkdtempSync } from "node:fs"; | |
| 8 | import { tmpdir } from "node:os"; | |
| 9 | import { join } from "node:path"; | |
| 10 | ||
| 11 | const NOW = Date.parse("2026-11-11T12:00:00Z"); | |
| 12 | const row = (kind: ExploreRow["kind"], n: Partial<ExploreRow["numbers"]>, shippedAt: string | null): ExploreRow => ({ | |
| 13 | kind, name: "a/<b>", url: "/a/b", description: "", shippedAt, score: 0, | |
| 14 | numbers: { forks: 0, ships: 0, likes: 0, awakeHours: 0, apps: 1, ...n }, | |
| 15 | }); | |
| 16 | ||
| 17 | test("the line is the hand-counted figures and the age", () => { | |
| 18 | expect(figuresOf(row("app", { forks: 3, ships: 5, likes: 1 }, "2026-11-09T08:00:00Z"), NOW)).toBe("3 forks, 5 ships, 1 like, shipped 2 days ago"); | |
| 19 | expect(figuresOf(row("app", {}, null), NOW)).toBe("0 forks, 0 ships, never shipped"); | |
| 20 | expect(figuresOf(row("app", {}, "2026-11-11T08:00:00Z"), NOW)).toBe("0 forks, 0 ships, shipped today"); | |
| 21 | expect(figuresOf(row("person", { forks: 3 }, null), NOW)).toBe(""); | |
| 22 | }); | |
| 23 | ||
| 24 | test("the API rows carry the same line", () => { | |
| 25 | const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-why-")), port: 0 }); | |
| 26 | const [out] = rowsWithWhy(app, { kind: "app", sort: "score", text: "", archived: false, updated: "all" }, [row("app", { forks: 2 }, null)]); | |
| 27 | app.close(); | |
| 28 | expect(out?.figures).toBe("2 forks, 0 ships, never shipped"); | |
| 29 | }); | |
| 30 | ||
| 31 | test("a seeded app's row on /explore carries the line, in one escaped meta line", async () => { | |
| 32 | const { serve } = await import("../src/http/server.ts"); | |
| 33 | const { createUser, getUserByName } = await import("../src/core/users.ts"); | |
| 34 | const { createRepo } = await import("../src/actions/repos.ts"); | |
| 35 | const { createApp: insertApp } = await import("../src/core/apps.ts"); | |
| 36 | const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-why-web-")), port: 0 }); | |
| 37 | const servers = await serve(app); | |
| 38 | try { | |
| 39 | const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-long-words-passphrase", adminIfFirst: true }); | |
| 40 | if (!made.ok) throw new Error("user"); | |
| 41 | const repo = await createRepo(app, getUserByName(app.db, "alice")!, { name: "tool", visibility: "public", description: "<b>x</b>" }); | |
| 42 | if (!repo.ok) throw new Error("repo"); | |
| 43 | insertApp(app.db, { repoId: repo.value.id, slug: "alice-tool", access: "public" }); | |
| 44 | const page = await (await fetch(`${servers.url}/explore?q=kind:app`)).text(); | |
| 45 | const meta = [...page.matchAll(/class="row-meta">([^<]*)</g)].map((m) => m[1]); | |
| 46 | expect(meta.some((m) => m === "0 forks, 0 ships, never shipped" || m!.startsWith("0 forks, 0 ships, never shipped ·"))).toBe(true); | |
| 47 | expect(page).not.toContain("<b>x</b>"); | |
| 48 | const api = (await (await fetch(`${servers.url}/api/v1/explore?q=kind:app`)).json()) as { items: { figures?: string }[] }; | |
| 49 | expect(api.items[0]?.figures).toBe("0 forks, 0 ships, never shipped"); | |
| 50 | } finally { | |
| 51 | servers.stop(); | |
| 52 | app.close(); | |
| 53 | } | |
| 54 | }); | |
| 55 | ||
| 56 | test("the line carries the figure the active sort ranks by, even at zero", () => { | |
| 57 | const r = row("app", { awakeHours: 7 }, null); | |
| 58 | expect(figuresOf(r, NOW, "likes")).toBe("0 forks, 0 ships, 0 likes, never shipped"); | |
| 59 | expect(figuresOf(r, NOW, "use")).toBe("0 forks, 0 ships, 7 h in use, never shipped"); | |
| 60 | expect(figuresOf(r, NOW)).toBe("0 forks, 0 ships, never shipped"); | |
| 61 | }); | |
| 62 | ||
| 63 | test("the row keeps its dated <time> and stays one ellipsised line", async () => { | |
| 64 | const css = (await import("../src/web/style/components.ts")).components; | |
| 65 | const meta = /^\.row-meta \{([^}]*)\}/m.exec(css)![1]!; | |
| 66 | expect(meta).toContain("white-space: nowrap"); | |
| 67 | expect(meta).toContain("text-overflow: ellipsis"); | |
| 68 | expect(meta).toContain("overflow: hidden"); | |
| 69 | expect(meta).toContain("display: block"); | |
| 70 | }); |
test/tui-explore-figures.test.ts added +9
| @@ -0,0 +1,9 @@ | ||
| 1 | /** The terminal's explorer rows say the page's figures line (#13483). */ | |
| 2 | import { expect, test } from "bun:test"; | |
| 3 | import { readFileSync } from "node:fs"; | |
| 4 | ||
| 5 | test("the TUI explorer row reads figuresOf, as the page does", () => { | |
| 6 | const src = readFileSync("src/tui/screens/dashboard.ts", "utf8"); | |
| 7 | const body = src.slice(src.indexOf("function numbersOf"), src.indexOf("function drawExplored")); | |
| 8 | expect(body).toContain("figuresOf(row, Date.now()"); | |
| 9 | }); |
new above
offline
Duplicates the age wording of shippedWords above (principle 1: nothing says itself twice). Reuse it, and keep the figure the active sort ranks by.