Public: anyone can read this; the crew can change it.
A missing docs page reads as a page: /docs/<unknown> and /docs/features/<unknown> answer the HTML not-found page to a browser #14378
Check · Review · Land · Live done — Landed and live in production.
/docs/ and /docs/features/ now answer the HTML not-found page to a browser, and JSON only when Accept ranks application/json first. I did not call keepplan or estimate and gave no time estimate. What changed The fix is in docPage in src/web/pages/docslink.ts, which both docsFile and docsFeature go through.
shipped production is serving it deploy 4ec2c16
3 earlier comments
/docs/<unknown> and /docs/features/<unknown> now answer the HTML not-found page to a browser, and JSON only when Accept ranks application/json first. I did not call keep_plan or estimate and gave no time estimate.
What changed
- The fix is in
docPageinsrc/web/pages/docs_link.ts, which bothdocsFileanddocsFeaturego through. A missing entry now returnsnotFoundPage(ctx)unless the caller prefers JSON, in which case it returnsnotFound()as before. - The new test file is
test/docs-not-found.test.ts. For both routes it checks the HTML 404 with a browserAcceptand the JSON 404 withAccept: application/json. A third test sweeps every GET route frombuildRouter(), fills the params with junk, and asserts no browser-facing path answers a JSON 404. - The new tests ran green with the fix. Stashing the
srcchange turned the three browser-facing ones red, and the two JSON-only ones passed either way, as expected. bun x tsc --noEmitis clean,design-lintis clean, andtest/docs-link.test.tspasses.gate.ts --fixrewrapped comments in one file and that went into the commit. I did not runbun testacross the whole suite; the forge does that on push.
What the sweep skips
- It skips paths that
missShapeclasses as machine or file (.png,.svg,.atom,.txt,/og/*,/api). - It also skips five data-feed routes that answer JSON or a stream by design:
/forges/:name/bill,/forges/:name/ready,/:owner/:name/stream,/:owner/:name/paths/:ref, and/origins/:id/r/:owner/:name/paths/:ref. They are listed in theFEEDSset in the test. - A route that never ends a response is skipped after 5 seconds rather than counted as a failure.
How to try it
Request /docs/start with Accept: text/html and you get the 404 page ("Nothing here"). The same request with Accept: application/json gets the JSON body.
Pushing The pre-push hook refused the push until a commit carried a "Try:" line, so I added an empty commit for it. You can squash it.
<!-- look-pages 381585aa1766 --> Look pages for 381585a, from the gate:
look pages (inferred): this pull changes src/web/pages/docs_link.ts; the forge pictures /docs (src/web/pages/docs_link.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
A missing docs page (/docs/<unknown> and /docs/features/<unknown>) now answers a browser with the HTML not-found page instead of a 235-byte JSON 404. JSON still comes back only when Accept ranks application/json first. The gate's "both doors" rule failed the earlier push because it edits src/web/pages/docs_link.ts with no matching terminal change; the new No door: line in the latest commit answers that rule and the gate now passes locally, but I haven't seen the forge's re-run.
- Fix: it is in
docPageinsrc/web/pages/docs_link.ts, which bothdocsFileanddocsFeaturego through. - Tests:
test/docs-not-found.test.tscovers both routes in both modes. It also sweeps every GET page route inbuildRouter()and finds no other path answering a browser a JSON 404. The sweep skips file and machine paths and five data-feed routes that answer JSON or a stream by design (bill,ready,stream, and the twopaths/:refroutes). Three of the five tests fail without the fix. - No door: the terminal has no docs not-found screen, so there was no terminal change to make. I added a
No door:line to a commit message instead, which is the escape the gate offers for an edit that shows nothing new. If a reviewer wants the terminal to show something here, that is a separate change. - Checks: I did not run the full suite here. I ran
bun x tsc --noEmit(clean),bun scripts/design-lint.ts(clean) andtest/docs-link.test.ts(passes). - Hook: the pre-push hook wants a "Try:" line in a commit, so the branch carries one empty commit for it. You can squash it.
To try it, request /docs/start with Accept: text/html and you get the 404 page ("Nothing here"). The same request with Accept: application/json gets the JSON body.
I added a No look: line to a new commit and pushed it. The gate inferred /docs as the look page because the pull edits docs_link.ts, but this change only touches a missing docs page's 404. The /docs index and the rendered docs look the same, so nothing needs a new picture. I didn't re-run the gate or any tests after this commit, since it changes only the commit message.
The change itself is the same as before. A missing docs page now gets the HTML not-found page in a browser and JSON only for Accept: application/json. The tests are in test/docs-not-found.test.ts.
If you'd rather have a picture of the not-found page, tell me which path to put in a Looks: line, for example /docs/start.
Works in the preview: /docs/start, /docs/nope and /docs/features/nope answer 404 text/html (the not-found page) to a browser; JSON stays for Accept: application/json. The fix is one line in docPage, which both routes share, and the 404 page is the existing chrome one, so no design-system departure. No terminal door is needed: the not-found page has no terminal counterpart. README untouched.
Two things I would do next:
- The FEEDS allowlist in the sweep is hand-kept; derive it from the router (or a marker on feed routes) so a new feed does not need a test edit, and a new JSON-404 page route is not silently excused.
- The not-found page has no Looks: picture; add one so the HTML 404 is seen, not only asserted.
Small note: the test path /docs/start reads like a real page; a name like /docs/nope-99 states the intent.
/docs/<unknown>and/docs/features/<unknown>now answer the HTML not-found page to a browser, and JSON only whenAcceptranksapplication/jsonfirst. I did not callkeep_planorestimateand gave no time estimate.What changed
docPageinsrc/web/pages/docs_link.ts, which bothdocsFileanddocsFeaturego through. A missing entry now returnsnotFoundPage(ctx)unless the caller prefers JSON, in which case it returnsnotFound()as before.test/docs-not-found.test.ts. For both routes it checks the HTML 404 with a browserAcceptand the JSON 404 withAccept: application/json. A third test sweeps every GET route frombuildRouter(), fills the params with junk, and asserts no browser-facing path answers a JSON 404.srcchange turned the three browser-facing ones red, and the two JSON-only ones passed either way, as expected.bun x tsc --noEmitis clean,design-lintis clean, andtest/docs-link.test.tspasses.gate.ts --fixrewrapped comments in one file and that went into the commit. I did not runbun testacross the whole suite; the forge does that on push.What the sweep skips
missShapeclasses as machine or file (.png,.svg,.atom,.txt,/og/*,/api)./forges/:name/bill,/forges/:name/ready,/:owner/:name/stream,/:owner/:name/paths/:ref, and/origins/:id/r/:owner/:name/paths/:ref. They are listed in theFEEDSset in the test.How to try it Request
/docs/startwithAccept: text/htmland you get the 404 page ("Nothing here"). The same request withAccept: application/jsongets the JSON body.Pushing The pre-push hook refused the push until a commit carried a "Try:" line, so I added an empty commit for it. You can squash it.
Closes #14366