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

Merged opened this

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

Merged

`/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

opened this

/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) in src/actions/explore.ts returns { query, unknown }. parseExploreQuery still exists and returns just the query. The unknown words are kept as typed and capped at five.
  • Note text: exploreNote builds 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. A kind: word gets use 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/explore and the MCP explore tool add a note field only when there is something to say. The status stays 200 and the tool schema and mcp-size are unchanged.
  • Tests: the new test/explore-unknown-words.test.ts covers 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.ts and test/tui-dashboard-explore.test.ts asserted the old behaviour. One expected sort:nonsense to come back as search text. The other expected "Nothing matches" for kind: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

commented

/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) in src/actions/explore.ts returns { query, unknown }. parseExploreQuery still exists and returns just the query. The unknown words are kept as typed and capped at five.
  • Note text: exploreNote builds 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. A kind: word gets use 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/explore and the MCP explore tool add a note field only when there is something to say. The status stays 200 and the tool schema and mcp-size are unchanged.
  • Tests: the new test/explore-unknown-words.test.ts covers 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.ts and test/tui-dashboard-explore.test.ts asserted the old behaviour. One expected sort:nonsense to come back as search text. The other expected "Nothing matches" for kind: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.

Changes requested — before the latest push

The page works in the preview: the note renders once, escaped, and results still show. Two things need fixing before it lands.

  1. 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.
  2. README: the explorer section around line 281 does not mention the note or the API/MCP note field. Add one line for each.

Smaller points are in the line comments.

commented

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 example Read as: kind:app · sort:nonsense is not a sort — use score, forks, …. test/tui-dashboard-explore.test.ts has 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 note field in /api/v1/explore and the MCP explore tool. That is one paragraph for the three, not one line each.
  • MCP: test/explore-unknown-words.test.ts now calls the explore tool over /mcp. It checks that note is returned for sort:bogus and absent for sort:forks.
  • Parser: the dangling else if is now } else if, and the over-long comment is re-wrapped.
Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs