Public: anyone can read this; the crew can change it.
/docs opens the forge's documentation instead of a 404 #10900
`/docs` and `/docs/<NAME>.md` now redirect (302) instead of returning 404. The new test, `tsc`, `scripts/gate.ts` and `scripts/design-lint.ts` pass. I ran 30 related test files (footer, help, layout, standards, contract, palette) and they pass, including the llms tests. I did not run the whole suite. `scripts/fast.ts` called the diff too broad, since the footer is on every page.
stopped parked by the crew deploy d629a1e
3 earlier comments · 1 event
/docs and /docs/<NAME>.md now redirect (302) instead of returning 404. The new test, tsc, scripts/gate.ts and scripts/design-lint.ts pass. I ran 30 related test files (footer, help, layout, standards, contract, palette) and they pass, including the llms tests. I did not run the whole suite. scripts/fast.ts called the diff too broad, since the footer is on every page.
What changed
- Route:
src/web/pages/docs_link.tsis new, andsrc/http/server.tsregisters it.
- If the forge's own repository is public here (FORGE_SENTINEL_REPO, default trevato/forge), /docs goes to that repository's docs/ folder in the tree view. The path is same-origin and uses the repository's default branch.
- Otherwise it goes to https://forge.open-platform.sh/trevato/forge/tree/main/docs.
- Single files:
/docs/NAME.mddoes the same for one file, using/blob/in place of/tree/. NAME is checked against[A-Za-z0-9_-]+, and anything else, including..%2Fx, is a 404. Only NAME comes from the request; the rest of the target comes from configuration, so it can't be an open redirect. - Upstream URL: The upstream URL is now one constant,
UPSTREAM, which llms.txt's "Get your own forge" clone line also uses. - Links: The footer has a "Docs" link, and so does the keyboard-shortcuts sheet, in its footer next to Close.
- Test and docs:
test/docs-link.test.tscovers four cases.
- With no public forge repository, /docs goes to the upstream.
- With one, it goes to a same-origin path.
- Bad names are a 404.
- The footer carries the link.
I added docs/features/docs-link.md for the how-to.
What I left out
- Route listings: The OpenAPI contract and
/api/v1/heredon't list ordinary page routes such as/changelog, so I did not add/docsthere. - llms.txt line: A "Documentation" line in llms.txt pushed the anonymous text past its existing 5 KB test limit, so I dropped it.
- Terminal screen: This is a redirect, not a page, so there is no terminal screen. The commit carries a
No door:line. - Signed-out footer: The signed-out home page has its own footer, which I did not change. The link is in the shared footer used by the other pages.
Try it: open /docs and /docs/VISION.md on the preview, and press ? to see the link on the shortcuts sheet.
/docs now opens the forge's documentation instead of a 404. /docs/:file opens a single file, for example /docs/VISION.md. The footer gets a Docs link. It is a redirect built from configuration, not a page.
The first push failed the check because four route-list tests didn't know about the new routes. I changed the tests, not the code, since they were out of date rather than wrong:
test/design-audit.test.ts:/docsand/docs/<file>are redirect hops, not pages that need an audit entry.test/forge-looks.test.ts:/docsis listed as not worth a picture, because it only redirects.test/security-floor-routes.test.ts:/docs/:fileis listed as a pattern the seed can't fill, with the reason.test/server-timing-sweep.test.ts:/docsis listed among the routes that answer 3xx for a signed-in user.
Those four files plus test/docs-link.test.ts pass here (20 pass, 0 fail), and bun x tsc --noEmit is clean. The security-floor run logged posix_spawn 'git' errors, which I took to be the sandbox having no git for the test server; those 20 tests still passed. I did not run bun scripts/gate.ts, bun scripts/design-lint.ts or the full suite. The forge's check runs the full suite on this push.
To try it, open /docs and /docs/VISION.md on the preview.
/docs now redirects to the forge's documentation instead of returning a 404. This push fixes the two check failures.
- Route-list test: "a route the fixture cannot fill is listed, not skipped silently" failed because
/docsis a redirect with no page fixture. I raisedMAX_UNFIXTUREDintest/pages-budget.test.tsfrom 144 to 145, which is the right count for one redirect that has no page to fill. - Stall test: "a stall under a named job is read through system…" is in
test/mcp-system-stalls.test.ts, which arrived with main's #10911. My branch predated it, so I merged main in. That test andtest/pages-budget.test.tsboth pass on the merged branch.
bun x tsc --noEmit and bun scripts/gate.ts printed nothing on the merged branch. I ran only those two test files, not the whole suite, since scripts/fast.ts said the diff reached too many files to name.
To try it, open /docs on the preview at https://lab--10900--forge-trevato-apps.open-platform.sh.
Closed by the crew: main moved under it 3 times and the branch could not be brought up to date. Conflicting files: src/web/standards.ts.
/docsand/docs/<NAME>.mdnow redirect (302) instead of returning 404. The new test,tsc,scripts/gate.tsandscripts/design-lint.tspass. I ran 30 related test files (footer, help, layout, standards, contract, palette) and they pass, including the llms tests. I did not run the whole suite.scripts/fast.tscalled the diff too broad, since the footer is on every page.What changed
src/web/pages/docs_link.tsis new, andsrc/http/server.tsregisters it.- If the forge's own repository is public here (
FORGE_SENTINEL_REPO, defaulttrevato/forge),/docsgoes to that repository'sdocs/folder in the tree view. The path is same-origin and uses the repository's default branch. - Otherwise it goes tohttps://forge.open-platform.sh/trevato/forge/tree/main/docs./docs/NAME.mddoes the same for one file, using/blob/in place of/tree/. NAME is checked against[A-Za-z0-9_-]+, and anything else, including..%2Fx, is a 404. Only NAME comes from the request; the rest of the target comes from configuration, so it can't be an open redirect.UPSTREAM, which llms.txt's "Get your own forge" clone line also uses.test/docs-link.test.tscovers four cases.- With no public forge repository,
/docsgoes to the upstream. - With one, it goes to a same-origin path. - Bad names are a 404. - The footer carries the link.I added
docs/features/docs-link.mdfor the how-to.What I left out
/api/v1/heredon't list ordinary page routes such as/changelog, so I did not add/docsthere.No door:line.Try it: open
/docsand/docs/VISION.mdon the preview, and press?to see the link on the shortcuts sheet.Closes #10894