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

/explore narrows to the apps started from one template, by a plain link that survives a reload #14740

Merged opened this

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

Merged

/explore?template= now lists only the forges whose spawn record names that template. It is visible to site admins only, because forges are the only rows that record a template. The new test file test/explore-template.test.ts, the neighbouring explore tests, tsc and gate.ts --fix are green.

Notes

shipped production is serving it deploy 7be111a

opened this

/explore?template=<name> now lists only the forges whose spawn record names that template. It is visible to site admins only, because forges are the only rows that record a template. The new test file test/explore-template.test.ts, the neighbouring explore tests, tsc and gate.ts --fix are green.

What changed

  • Where the filter lives: the issue named src/web/pages/explorer.ts, but that file is the code-browser file tree. The real explore page is src/actions/explore.ts (the query) plus src/web/studio/explore.ts (the chips and empty state), so the change went there. #14640 may be editing the file tree and not these two, so it should merge cleanly.
  • Where it's recorded: a template is stored per forge in spawn/<name>.json (Child.template). Apps and people have no such record, so template: removes their rows.
  • Validation: the value must pass parseTemplate, which accepts a built-in id or an owner/name. Anything else is dropped with a 303 and a note, like other bad filter words. A valid value is compared by plain equality against the spawn record, with no SQL involved.
  • Unknown name: a well-formed name that matches nothing shows "No apps were started from <name>" with a hint.
  • Clear link: an active template:<name> chip appears in the existing filter chips, and its link removes only that filter.
  • Stacking: it combines with kind, q and the other filters. The URL parameter, the query line, the MCP/API parameter list and the "is filtered" check all know it.
  • Tests: the new file covers a known template, an unknown one, the clear link, stacking with other filters, and rejection of a malformed value.

Left out

  • Non-admins see nothing under template=, because spawned forges are an admin's to see. Showing them would be a separate decision about who sees forges.
  • App repositories don't record a template, so they can't be filtered. That would need a new column.
  • "Known" means a valid shape, not an existing template, so a well-formed but unused name gives the empty answer and not a refusal.

Try it: as an admin, open /explore?template=trevato/shop, then press the chip to clear it.

[
  {"go": "/explore?template=trevato/shop", "look": "the Active filters chip row and the list", "expect": "only forges started from that template, a template:trevato/shop chip with ×"},
  {"go": "/explore?template=nobody/nothing", "look": "the empty state", "expect": "No apps were started from nobody/nothing, with the chip still shown to clear it"},
  {"go": "/explore?template=trevato/shop&kind=forge", "look": "the chips", "expect": "two chips; removing one keeps the other"}
]

Closes #14646

7 earlier comments · 1 event
commented

/explore?template=<name> now lists only the forges whose spawn record names that template. It is visible to site admins only, because forges are the only rows that record a template. The new test file test/explore-template.test.ts, the neighbouring explore tests, tsc and gate.ts --fix are green.

What changed

  • Where the filter lives: the issue named src/web/pages/explorer.ts, but that file is the code-browser file tree. The real explore page is src/actions/explore.ts (the query) plus src/web/studio/explore.ts (the chips and empty state), so the change went there. #14640 may be editing the file tree and not these two, so it should merge cleanly.
  • Where it's recorded: a template is stored per forge in spawn/<name>.json (Child.template). Apps and people have no such record, so template: removes their rows.
  • Validation: the value must pass parseTemplate, which accepts a built-in id or an owner/name. Anything else is dropped with a 303 and a note, like other bad filter words. A valid value is compared by plain equality against the spawn record, with no SQL involved.
  • Unknown name: a well-formed name that matches nothing shows "No apps were started from <name>" with a hint.
  • Clear link: an active template:<name> chip appears in the existing filter chips, and its link removes only that filter.
  • Stacking: it combines with kind, q and the other filters. The URL parameter, the query line, the MCP/API parameter list and the "is filtered" check all know it.
  • Tests: the new file covers a known template, an unknown one, the clear link, stacking with other filters, and rejection of a malformed value.

Left out

  • Non-admins see nothing under template=, because spawned forges are an admin's to see. Showing them would be a separate decision about who sees forges.
  • App repositories don't record a template, so they can't be filtered. That would need a new column.
  • "Known" means a valid shape, not an existing template, so a well-formed but unused name gives the empty answer and not a refusal.

Try it: as an admin, open /explore?template=trevato/shop, then press the chip to clear it.

[
  {"go": "/explore?template=trevato/shop", "look": "the Active filters chip row and the list", "expect": "only forges started from that template, a template:trevato/shop chip with ×"},
  {"go": "/explore?template=nobody/nothing", "look": "the empty state", "expect": "No apps were started from nobody/nothing, with the chip still shown to clear it"},
  {"go": "/explore?template=trevato/shop&kind=forge", "look": "the chips", "expect": "two chips; removing one keeps the other"}
]
commented

<!-- look-pages 68123aad64ac --> Look pages for 68123aa, from the gate:

  • look pages (inferred): this pull changes src/web/studio/explore.ts; the forge pictures /explore (src/web/studio/explore.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

Explore can now narrow to forges started from one template with template=<id or owner/name>. A chip clears the filter. The check's "both doors" rule had failed this pull, and I've now answered it.

Why the rule is answered with a note, not a TUI change: the terminal's search box reads its line through readExploreLine in src/actions/explore.ts, the same reader the web and API use. template:x already works there with no change under src/tui/. I added an empty commit carrying a No door: line saying so, which the gate accepts.

What changed:

  • template is a filter parameter and a template: word in the search line. A value that isn't a valid template id or owner/name is refused with a note.
  • The filter matches the template recorded when a forge was started, by equality in code. It covers forges only, since apps and people have no such record, and only admins see forge rows in Explore at all.
  • The chip is in src/web/studio/explore.ts.
  • Tests are in test/explore-template.test.ts.

What I ran:

  • bun x tsc --noEmit is clean.
  • bun test test/explore-template.test.ts passes (4 tests).
  • bun scripts/gate.ts --fix rewrapped nothing, and the one "long comment" note is informational.
  • Only that one test file ran, not other suites.
  • The gate step was not re-run to a pass here. It was still red on the "both doors" rule locally, because it only reads the commit message once pushed.

What I left out: no TUI-specific control for the filter, and no template picker. It is a plain link and a typed word.

Try it: open /explore?template=<id> as an admin and check that the chip appears and clears. In the terminal, search template:<id>.

[{"go":"/explore?template=nope/","look":"the search note","expect":"says it is not a template, use a template id or owner/name"},{"go":"/explore?template=<a template id>","look":"the chip and the rows","expect":"only forges started from that template, and a chip that returns to /explore when followed"}]
commented

<!-- look-pages 1e059a4092e1 --> Look pages for 1e059a4, from the gate:

  • look pages (inferred): this pull changes src/web/studio/explore.ts; the forge pictures /explore (src/web/studio/explore.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

The look-pages comment is the gate's own notice, not a change request, so I changed nothing and pushed nothing. It says the forge will picture /explore, which is the page this pull changes (src/web/studio/explore.ts), and /explore is the right page to picture.

I agree with the inference, so I added no Looks: or No look: line to override it.

To check it by hand, open /explore?template=<a template id> as an admin. Only forges started from that template should show, and the chip should clear the filter back to /explore. A value that isn't a template id or owner/name (e.g. /explore?template=nope/) should show the note "is not a template, use a template id or owner/name".

[{"go":"/explore?template=nope/","look":"the search note","expect":"says it is not a template, use a template id or owner/name"},{"go":"/explore?template=<a template id>","look":"the chip and the rows","expect":"only forges started from that template, and a chip that returns to /explore when followed"}]
Changes requested — before the latest push

The filter works in the preview: the chip shows and clears, and the value is validated and matched by equality, never in SQL. Two things must change before it lands.

First: no docs/features/explore.md update. The template: word and ?template= parameter have no how-to; add them there (not in README). Both doors: the terminal reads through readExploreLine, so the note is acceptable, but the how-to must say template:<id> works in the terminal search too.

Second: the empty state says 'No apps were started from X' for every empty result, including a non-admin, who never sees forge rows at all. A person who is not an admin is told a template has no apps when the truth is that they cannot see them. Word it for that case (or say the filter lists forges only visible to admins).

Also: test helper has is includes(name) in both branches, so it is a weaker check than it looks; match the row markup. Add a non-admin case to the tests.

commented

Both requested changes are in and pushed. bun test test/explore-template.test.ts passes (5 tests) and tsc is clean. I did not run other suites or the design-lint.

  • Docs: docs/features/explore.md now describes template=<name>, template:<name>, and the template:<name> chip that clears the filter. It says forges only and admins only, and that template:<id> works in the terminal search too, via readExploreLine.
  • Empty state: an empty template result now reads "No forges to show for X" with the note "Only admins can list forges started from a template." The sentence is true for any viewer. It is in src/web/studio/explore.ts.
  • Tests: has now matches the row link markup, <a …>name</a>, so a name appearing in the filter box or chip no longer counts. A new test covers a signed-in non-admin and a guest. Both get the new wording and no forge rows.
[{"go":"/explore?template=nobody/nothing","look":"the empty state","expect":"title says No forges to show for nobody/nothing, note says only admins can list forges started from a template"},{"go":"/explore?template=<a template id> signed out or as a non-admin","look":"the list","expect":"no forge rows, same plain sentence"}]
commented

<!-- look-pages 2654b0120191 --> Look pages for 2654b01, from the gate:

  • look pages (inferred): this pull changes src/web/studio/explore.ts; the forge pictures /explore (src/web/studio/explore.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

No code change this time, so I pushed nothing. The check's red is timing under load and failures that already exist on main.

  • Already red on main at 593fb67: outbound-sweep, docs-link, llms-budget, fetch-timeout, pages-budget and page-budget. The forge's own log says these aren't counted against this pull.
  • The one it did count: require-review refuses the merge until the head is approved in test/tui-workflows.test.ts. That test drives the terminal's pull page and never touches Explore or the template filter. This pull only changes src/actions/explore.ts, src/web/studio/explore.ts, docs/features/explore.md and test/explore-template.test.ts.
  • It passes here: test/tui-workflows.test.ts passed on its own (8 of 8). Two further runs of it together with test/engine-split.test.ts (22 of 22) were also green. The third run timed out in the sandbox, and I did not wait for its result.
  • Where it likely failed: the test waits on the terminal's asynchronous load. A shard running under heavy load, 346 s across 2491 files, can plausibly miss that wait. I did not confirm that is what happened.
  • Also in the failure list: a stream that resumes while the engine writes in test/engine-split.test.ts. It passed in the same local runs and is also unrelated to Explore.

What the pull does: Explore narrows to forges started from one template through a plain template= link, with a chip that clears it. The terminal reaches the same filter through the shared line reader. docs/features/explore.md has the how-to, and test/explore-template.test.ts covers it, including an empty state that is true for non-admins.

What to look at: src/actions/explore.ts for the filter, src/web/studio/explore.ts for the chip.

How to try it: open /explore?template=<name> on the preview. A chip names the template, and following it clears the filter.

A re-run of the check on this head should show tui-workflows green.

Approved

Earlier asks: docs how-to now in docs/features/explore.md (README untouched) - met. Empty state worded for every viewer, not claiming no apps exist - met. Test row matcher tightened and a non-admin/guest test added - met. The terminal reaches the filter through the shared readExploreLine, so both doors hold. Value is validated by parseTemplate and matched by equality in code, never SQL. Works with JS off (plain link, chip is an anchor).

Next two things: (1) Non-blocking: an admin who types an unknown template sees "Only admins can list forges..." which is true but not useful to them; a line saying no forge was started from it would read better for admins. (2) Non-blocking: recording a template on app repos would let the filter cover apps, as the scout noted.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs