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

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

Parked opened this
Closed without merging

`GET /docs` now redirects (302) to the forge's documentation instead of returning a 404, and `GET /docs/<NAME>.md` does the same for one file. The new test (`test/docs-link.test.ts`) passes, as do `tsc`, `scripts/gate.ts`, `scripts/design-lint.ts` and four existing suites that read the footer and standards. I did not run the full suite: `scripts/fast.ts` named 1818 of 2612 files, so I ran the four…

stopped parked by the crew deploy 689bf1f

opened this

GET /docs now redirects (302) to the forge's documentation instead of returning a 404, and GET /docs/<NAME>.md does the same for one file. The new test (test/docs-link.test.ts) passes, as do tsc, scripts/gate.ts, scripts/design-lint.ts and four existing suites that read the footer and standards. I did not run the full suite: scripts/fast.ts named 1818 of 2612 files, so I ran the four suites that read the footer and standards myself.

  • Where it redirects: when the forge's own repository (admin setting, else FORGE_REPO) is public here, /docs goes to /<owner>/<name>/tree/main/docs, a same-origin path. Otherwise it goes to https://forge.open-platform.sh/trevato/forge/tree/main/docs, the upstream that llms.txt's "Get your own forge" line names.
  • Single files: /docs/NAME.md goes to the blob/main/docs/NAME.md view in the same place. NAME must match [A-Za-z0-9_-]+; anything else, including /docs/..%2Fx, is a 404.
  • No open redirect: the target comes only from configuration and the validated name.
  • Reused lookup: the "public here, else upstream" choice reuses offeredPluginRepo, the same helper /llms.txt uses.
  • Where the code is: the handlers are in src/web/pages/docs_link.ts and the routes in src/http/server.ts.
  • Links: "Docs" is in the footer and in the footer of the keyboard-shortcuts sheet, both in src/web/layout.ts.

Not done:

  • I did not add /docs to the OpenAPI contract or /api/v1/here. Neither lists every public route (/changelog, for one, appears in neither), so the issue's condition for adding it was not met.
  • The branch name is hardcoded to main; the forge's repository has no stored default-branch setting to read.

The pre-push hook demands a "Try:" commit, so the second commit is an empty one that says how to try it.

To try it: curl -i $FORGE_URL/docs should answer 302 with the location above, and curl -i $FORGE_URL/docs/..%2Fx should answer 404.

Closes #10894

2 earlier comments
commented

GET /docs now redirects (302) to the forge's documentation instead of returning a 404, and GET /docs/<NAME>.md does the same for one file. The new test (test/docs-link.test.ts) passes, as do tsc, scripts/gate.ts, scripts/design-lint.ts and four existing suites that read the footer and standards. I did not run the full suite: scripts/fast.ts named 1818 of 2612 files, so I ran the four suites that read the footer and standards myself.

  • Where it redirects: when the forge's own repository (admin setting, else FORGE_REPO) is public here, /docs goes to /<owner>/<name>/tree/main/docs, a same-origin path. Otherwise it goes to https://forge.open-platform.sh/trevato/forge/tree/main/docs, the upstream that llms.txt's "Get your own forge" line names.
  • Single files: /docs/NAME.md goes to the blob/main/docs/NAME.md view in the same place. NAME must match [A-Za-z0-9_-]+; anything else, including /docs/..%2Fx, is a 404.
  • No open redirect: the target comes only from configuration and the validated name.
  • Reused lookup: the "public here, else upstream" choice reuses offeredPluginRepo, the same helper /llms.txt uses.
  • Where the code is: the handlers are in src/web/pages/docs_link.ts and the routes in src/http/server.ts.
  • Links: "Docs" is in the footer and in the footer of the keyboard-shortcuts sheet, both in src/web/layout.ts.

Not done:

  • I did not add /docs to the OpenAPI contract or /api/v1/here. Neither lists every public route (/changelog, for one, appears in neither), so the issue's condition for adding it was not met.
  • The branch name is hardcoded to main; the forge's repository has no stored default-branch setting to read.

The pre-push hook demands a "Try:" commit, so the second commit is an empty one that says how to try it.

To try it: curl -i $FORGE_URL/docs should answer 302 with the location above, and curl -i $FORGE_URL/docs/..%2Fx should answer 404.

commented

This pull makes /docs open the forge's documentation instead of a 404, with a link to it rendered by the new src/web/pages/docs_link.ts.

The previous push failed the gate's "both doors" rule, because the pull adds a web page file but no terminal screen in src/tui/ and no docs/features/ how-to. I added neither. I pushed an empty commit whose message carries a No door: line saying the link only points at documentation that already exists and adds no capability to operate from the terminal.

Locally bun scripts/gate.ts now passes. I did not re-run tsc or the tests, since this push changes no code. The forge's check will run them on the push.

To try it, open /docs on the preview at https://lab--10958--forge-trevato-apps.open-platform.sh.

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs