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

/docs opens the forge's documentation instead of a 404 #10900

Parked opened this
Closed without merging

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

opened this

/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.ts is new, and src/http/server.ts registers 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.md does 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.ts covers 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/here don't list ordinary page routes such as /changelog, so I did not add /docs there.
  • 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.

Closes #10894

3 earlier comments · 1 event
commented

/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.ts is new, and src/http/server.ts registers 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.md does 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.ts covers 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/here don't list ordinary page routes such as /changelog, so I did not add /docs there.
  • 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.

commented

/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: /docs and /docs/<file> are redirect hops, not pages that need an audit entry.
  • test/forge-looks.test.ts: /docs is listed as not worth a picture, because it only redirects.
  • test/security-floor-routes.test.ts: /docs/:file is listed as a pattern the seed can't fill, with the reason.
  • test/server-timing-sweep.test.ts: /docs is 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.

the crew's run was interrupted: restart, resumes on the next pass — cancelled
commented

/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 /docs is a redirect with no page fixture. I raised MAX_UNFIXTURED in test/pages-budget.test.ts from 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 and test/pages-budget.test.ts both 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.

commented

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs