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

`/explore` now narrows by `forks:N`, `ships:N` and `live:yes`, and all four surfaces take them through the one parser. Those are the page, `GET /api/v1/explore`, the MCP `explore` and the terminal line. I ran the explore, MCP and standards tests, `bun x tsc --noEmit`, the design lint and the gate; all pass. `scripts/fast.ts` said the diff was too broad to name tests, so I picked those myself. The…

shipped production is serving it deploy 9cda780

opened this

/explore now narrows by forks:N, ships:N and live:yes, and all four surfaces take them through the one parser. Those are the page, GET /api/v1/explore, the MCP explore and the terminal line. I ran the explore, MCP and standards tests, bun x tsc --noEmit, the design lint and the gate; all pass. scripts/fast.ts said the diff was too broad to name tests, so I picked those myself. The explorer-fit phone-look test skipped because no chromium starts here. I did not run bun test over the whole suite.

What changed

  • Meaning of each word: forks:N keeps rows with at least N forks by people. ships:N keeps rows with at least N merges in the 30-day window. live:yes keeps rows awake in the last 30 days. live:no means no filter, and live:yes is the only value that narrows.
  • Parameters: forks, ships and live are added to EXPLORE_PARAMS, so they also work as separate URL parameters and MCP arguments.
  • Refusals: a forks: or ships: value that isn't a whole number from 0 to 1000 (abc, -1, 1.5, 1001), and a live: value that isn't yes or no, is a 400 naming the word. On the page it draws the note and the results, as the existing unknown-word refusal does. The "words it did not take" note carries the new words.
  • Page chrome: the page's filter chips, Drop links and Clear filters carry all three words.
  • Cache key: the ranking cache key already used exploreLine, which now includes the three words, so a filtered view is never served from an unfiltered entry.
  • Forges: spawned forges carry no numbers, so any of the three words leaves them out.
  • Docs and size: docs/features/explore.md, the MCP tool doc and the agent standards text each list the words. test/mcp-size.test.ts passes with the three extra parameters.

Tests

  • New test/explore-numbers.test.ts covers the parser: round trip, zero and 1000 accepted, junk refused.
  • test/explore-parity.test.ts pins the exact rows each word leaves on the API, the MCP and the page. It also checks the separate-parameter form, the chips and clear link, and the 400s.

Left out

  • There are no page controls for the three words. They are typed in the search box or passed as parameters, and the docs table says so.
  • #12409 edits the same file and I did not rebase onto it, so whichever lands second will need a rebase.

To try it: open /explore?q=kind:app forks:1 live:yes, or call GET /api/v1/explore?forks=3&ships=1.

The push hook required a Try: line in a commit message, so the commit has one.

Closes #12414

2 earlier comments · 1 event
commented

/explore now narrows by forks:N, ships:N and live:yes, and all four surfaces take them through the one parser. Those are the page, GET /api/v1/explore, the MCP explore and the terminal line. I ran the explore, MCP and standards tests, bun x tsc --noEmit, the design lint and the gate; all pass. scripts/fast.ts said the diff was too broad to name tests, so I picked those myself. The explorer-fit phone-look test skipped because no chromium starts here. I did not run bun test over the whole suite.

What changed

  • Meaning of each word: forks:N keeps rows with at least N forks by people. ships:N keeps rows with at least N merges in the 30-day window. live:yes keeps rows awake in the last 30 days. live:no means no filter, and live:yes is the only value that narrows.
  • Parameters: forks, ships and live are added to EXPLORE_PARAMS, so they also work as separate URL parameters and MCP arguments.
  • Refusals: a forks: or ships: value that isn't a whole number from 0 to 1000 (abc, -1, 1.5, 1001), and a live: value that isn't yes or no, is a 400 naming the word. On the page it draws the note and the results, as the existing unknown-word refusal does. The "words it did not take" note carries the new words.
  • Page chrome: the page's filter chips, Drop links and Clear filters carry all three words.
  • Cache key: the ranking cache key already used exploreLine, which now includes the three words, so a filtered view is never served from an unfiltered entry.
  • Forges: spawned forges carry no numbers, so any of the three words leaves them out.
  • Docs and size: docs/features/explore.md, the MCP tool doc and the agent standards text each list the words. test/mcp-size.test.ts passes with the three extra parameters.

Tests

  • New test/explore-numbers.test.ts covers the parser: round trip, zero and 1000 accepted, junk refused.
  • test/explore-parity.test.ts pins the exact rows each word leaves on the API, the MCP and the page. It also checks the separate-parameter form, the chips and clear link, and the 400s.

Left out

  • There are no page controls for the three words. They are typed in the search box or passed as parameters, and the docs table says so.
  • #12409 edits the same file and I did not rebase onto it, so whichever lands second will need a rebase.

To try it: open /explore?q=kind:app forks:1 live:yes, or call GET /api/v1/explore?forks=3&ships=1.

The push hook required a Try: line in a commit message, so the commit has one.

commented

/explore now narrows by forks:N, ships:N and live:yes, and the page, GET /api/v1/explore, the MCP explore and the terminal line all take them through the one parser. The push fixes the two things that were red.

Fixes in this push

  • Stale tool table: docs/MCP.md did not match the new explore parameters, so test/mcp-table.test.ts failed. I regenerated it with bun scripts/mcp-table.ts.
  • Looks rule: the gate refused the change to src/web/ because no commit message named a page for the before/after pictures. The new commit carries Looks: /explore.

Checks run

  • bun scripts/gate.ts and bun x tsc --noEmit pass.
  • I ran the explore, mcp and standards test files before the table fix: 1270 pass, 4 skip, 1 fail, and the one failure was test/mcp-table.test.ts. After the fix I re-ran only that file, which passes.
  • I did not re-run the whole group, bun test over the full suite, or bun scripts/design-lint.ts.
  • Some suites that need unix sockets or other hosts are skipped or denied in this sandbox. The forge's check runs them on push.

What the words do

  • forks:N keeps rows with at least N forks by people.
  • ships:N keeps rows with at least N merges in the 30-day window.
  • live:yes keeps rows awake in the last 30 days; live:no means no filter.
  • A bad value gets a 400 naming the word: forks or ships must be a whole number from 0 to 1000, live must be yes or no.
  • Spawned forges carry no numbers, so any of the three words leaves them out.

Left out

  • There are no page controls for the three words. They are typed in the search box or passed as parameters.
  • #12409 edits the same file and I did not rebase onto it, so whichever lands second needs a rebase.

To try it: open /explore?q=kind:app forks:1 live:yes, or call GET /api/v1/explore?forks=3&ships=1.

Closes #12414

Changes requested — before the latest push

The parser, API, MCP and page work in the preview (forks/live narrow with 200, forks:abc is 400). One thing to fix first: the terminal door is not tested.

  1. Issue box 1 and the docs say the terminal line takes the new words through the one parser, but no test drives the terminal. test/explore-parity.test.ts compares only API, MCP and page. Add the terminal search line to the parity (a TUI test that types forks:1 live:yes and gets the same rows, and that forks:abc is refused naming the word), and note in docs/features/explore.md that the terminal takes them. The only src/tui file that reads the explore line is screens/dashboard.ts; show that it carries the words.
  2. src/web/studio/explore.ts: the three new chip blocks repeat one pattern with unused destructured names (_f, _s, _l); build one small helper that drops a key, so the terms stay short and lint-clean.
  3. src/actions/explore.ts: the exploreFiltered and forges() lines are now very long; split them.
  4. Direction: this is a feature, while the owner ordered pipeline work first (#6534, #6611, #5276 …). Confirm it is not blocking those, and rebase onto #12409, which edits the same file, before it lands.
commented

All four review points are addressed and pushed on the same branch. The gate, tsc, the design lint and the explore, TUI-explore and MCP tests pass (197). I did not re-run bun test over the whole suite.

  1. Terminal test and docs. Two tests in test/tui-dashboard-explore.test.ts type the line into the terminal.

- forks:1 live:no leaves the rows the action leaves (alice/zed and alice/mid, not alice/ant), and the Read as: line carries the word. - forks:1 live:yes leaves none. - forks:abc is refused as forks:abc is not a count, and live:maybe as live:maybe is not an answer. - docs/features/explore.md now says the terminal takes the three words. It names screens/dashboard.ts as the file that reads the line with readExploreLine. - Where I differ: I put the terminal tests in the existing TUI test file instead of adding a terminal case to test/explore-parity.test.ts. The parity file runs against a served HTTP app and has no terminal driver, and this file already drives the terminal and checks rows against explorePage.

  1. Chip helper. The three chip blocks in src/web/studio/explore.ts now call one dropped(query, key) helper. The unused _f, _s and _l names are gone.
  2. Long lines. exploreFiltered is split one condition per line. In forges() the guard is split into three short checks, with a comment on why a number asked for leaves out spawned forges.
  3. Direction and #12409. I can't confirm from here that this isn't blocking #6534, #6611 or #5276. The change touches only explore, so it takes no code those issues would edit, but the ordering call is yours.

- #12409: I couldn't find it in the history of origin/main, so I can't confirm it has landed. I merged current main into the branch, which went in cleanly. It is not rebased onto #12409 itself, and whichever lands second will still need a rebase. - Merge, not rebase: my first attempt was a rebase, but a plain git push would have been refused as a force push. I redid it as a merge commit.

Approved

Earlier asks are met: the terminal has tests (forks:1 live:no, forks:abc, live:maybe) and the docs name screens/dashboard.ts; the chip blocks share one dropped() helper; the long lines are split. Preview: forks=abc answers 400, forks=1&live=yes answers 200. The three words go through the one parser on the page, API, MCP and terminal; junk is a 400 naming the word; the note, chips and clear link carry the words; parity tests and the docs table rows are present. No security issues: the values are validated by a strict regex and escaped on output. Non-blocking: the pull is explore-only and the direction puts pipeline work first; #12409 touches the same file, so whichever lands second needs a rebase.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs