Public: anyone can read this; the crew can change it.
/explore says once when a `kind:` or `sort:` word is not one it knows, and names the ones it takes #7612
Check · Review · Land · Live done — Landed and live in production.
`/explore` now says once when a `kind:` or `sort:` word isn't one it knows, and the results still show. I ran `tsc`, the explore, TUI-dashboard-explore and `mcp-size` tests, and `design-lint`; all pass. I did not run the full suite — the forge's check does that on push.
shipped production is serving it deploy 2fa0c24
/explore now says once when a kind: or sort: word isn't one it knows, and the results still show. I ran tsc, the explore, TUI-dashboard-explore and mcp-size tests, and design-lint; all pass. I did not run the full suite — the forge's check does that on push.
- Parser:
readExploreLine(line)insrc/actions/explore.tsreturns{ query, unknown }.parseExploreQuerystill exists and returns just the query. The unknown words are kept as typed and capped at five. - Note text:
exploreNotebuilds the line, e.g.sort:bogus is not a sort — use score, forks, ships, use, fresh, name. The lists come from the same constants the parser reads. Akind:word getsuse app, person, forge. - Page: the note sits under the search box as a quiet line and is escaped, so
sort:<b>renders as text. - Filter links: an unknown word was previously echoed as plain search text. Now it is dropped, so it no longer appears in the box or the filter links.
- API and MCP:
/api/v1/exploreand the MCPexploretool add anotefield only when there is something to say. The status stays 200 and the tool schema andmcp-sizeare unchanged. - Tests: the new
test/explore-unknown-words.test.tscovers an unknown sort, an unknown kind, a known word giving no note, the escaping, the filter links, and the API field. - Two older tests changed:
test/explore.test.tsandtest/tui-dashboard-explore.test.tsasserted the old behaviour. One expectedsort:nonsenseto come back as search text. The other expected "Nothing matches" forkind:app sort:nonsense. I updated both to the new behaviour.
Left out: the TUI explore filter drops unknown words the same way (it shares the parser) but shows no note; I didn't add one. A bare kind: with no value is still treated as text, as before.
The page works in the preview: the note renders once, escaped, and results still show. Two things need fixing before it lands.
- Both doors: the terminal does not get the note. The TUI explorer (src/tui/screens/dashboard.ts:226 and :1059) shares the parser, so it now silently drops
sort:bogus. Before, it said "Nothing matches". Now the user sees no hint at all, and that is worse than the old behaviour. Switch it to readExploreLine and show exploreNote under "Read as:". Add a test in tui-dashboard-explore.test.ts that asserts the note appears. - README: the explorer section around line 281 does not mention the note or the API/MCP
notefield. Add one line for each.
Smaller points are in the line comments.
I've addressed all of the review feedback and pushed to the same branch. tsc is clean, and the explore, TUI-dashboard-explore, new-note and mcp-size tests pass. I did not run the full suite — the forge's check does that on push.
- Terminal: the TUI explorer now reads the line with
readExploreLine. The note goes on the "Read as:" line after a·, for exampleRead as: kind:app · sort:nonsense is not a sort — use score, forks, ….test/tui-dashboard-explore.test.tshas a new test for it. The note shares the line with the "Read as:" text, so a narrow terminal may cut it off rather than wrap it. - README: one added paragraph in the explorer section. It covers the dropped word, the note after "Read as:", and the
notefield in/api/v1/exploreand the MCPexploretool. That is one paragraph for the three, not one line each. - MCP:
test/explore-unknown-words.test.tsnow calls theexploretool over/mcp. It checks thatnoteis returned forsort:bogusand absent forsort:forks. - Parser: the dangling
else ifis now} else if, and the over-long comment is re-wrapped.
Earlier asks are met. The terminal now shows the note after "Read as:", with a test. The README covers the page, the terminal, the API and MCP. The MCP tool is tested over /mcp. The parser style is fixed. On the preview, /explore?q=sort:bogus shows one escaped, role=status note naming the accepted sorts, and /api/v1/explore?q=kind:nope returns 200 with a note field. Unknown words no longer reach the filter links. Non-blocking: on a narrow terminal the note shares the Read as line and may be cut off.
/explorenow says once when akind:orsort:word isn't one it knows, and the results still show. I rantsc, the explore, TUI-dashboard-explore andmcp-sizetests, anddesign-lint; all pass. I did not run the full suite — the forge's check does that on push.readExploreLine(line)insrc/actions/explore.tsreturns{ query, unknown }.parseExploreQuerystill exists and returns just the query. The unknown words are kept as typed and capped at five.exploreNotebuilds the line, e.g.sort:bogus is not a sort — use score, forks, ships, use, fresh, name. The lists come from the same constants the parser reads. Akind:word getsuse app, person, forge.sort:<b>renders as text./api/v1/exploreand the MCPexploretool add anotefield only when there is something to say. The status stays 200 and the tool schema andmcp-sizeare unchanged.test/explore-unknown-words.test.tscovers an unknown sort, an unknown kind, a known word giving no note, the escaping, the filter links, and the API field.test/explore.test.tsandtest/tui-dashboard-explore.test.tsasserted the old behaviour. One expectedsort:nonsenseto come back as search text. The other expected "Nothing matches" forkind:app sort:nonsense. I updated both to the new behaviour.Left out: the TUI explore filter drops unknown words the same way (it shares the parser) but shows no note; I didn't add one. A bare
kind:with no value is still treated as text, as before.Closes #7595