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

A public app's page tells an outside agent in its first 500 bytes how to report a problem and offer a change #13702

Merged opened this

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

Merged

A public repository's page now puts the report and offer links in the first 500 bytes of its HTML. The same URLs are in its JSON-LD and in the repository's generated llms text. The three tests in test/muse-find.test.ts pass.

Notes

shipped production is serving it deploy 59903fa

opened this

A public repository's page now puts the report and offer links in the first 500 bytes of its HTML. The same URLs are in its JSON-LD and in the repository's generated llms text. The three tests in test/muse-find.test.ts pass. I also ran 5 related files (agents-md, apps-report, report-discovery, muse-report-journey, claim-home-csp) and 3 more (v1-proven, no-polling, muse-journey), and all pass.

I never ran the whole fast set, because the layout change makes it about 2,186 files. bun scripts/gate.ts --fix, bun x tsc --noEmit and design-lint came back with nothing flagged, but I only looked at the tail of their output.

  • Head links: layout.ts emits <link rel="help" href="…"> for each help link pageLinks returns, straight after <meta charset>. For a public repository with reports open, those are /{o}/{n}/report, /api/v1/repos/{o}/{n}/reports and, where the owner opened contributions, /api/v1/contribute. The Link header is unchanged, and the head links no longer repeat later in the head.
  • JSON-LD: repoStructuredData in structured_data.ts adds a SoftwareSourceCode object to the repo page, including the empty-repo view. Its potentialAction list has the same URLs as CommunicateAction targets.
  • llms text: the generated /{o}/{n}/AGENTS.md now also names the JSON reports endpoint and /api/v1/contribute.
  • Not shown: a private repository, or one with reports closed, gets none of this. /api/v1/contribute is listed only when the owner has opened it.

I used rel="help", not rel="report", because help is what the existing Link header and muse-journey already use. report isn't a registered link relation, so I didn't add a second vocabulary.

I left the global /llms.txt repo listing alone. Adding two URLs to every line would swell it, and it already says /{owner}/{name}/report needs no account. A repo that ships its own AGENTS.md is served as written, so the new JSON and offer line only appears in the generated one.

The first push was refused by a pre-push hook that wants a "Try:" line in the commit message, so I amended the commit to include one.

Closes #13662

7 earlier comments · 2 events
commented

A public repository's page now puts the report and offer links in the first 500 bytes of its HTML. The same URLs are in its JSON-LD and in the repository's generated llms text. The three tests in test/muse-find.test.ts pass. I also ran 5 related files (agents-md, apps-report, report-discovery, muse-report-journey, claim-home-csp) and 3 more (v1-proven, no-polling, muse-journey), and all pass.

I never ran the whole fast set, because the layout change makes it about 2,186 files. bun scripts/gate.ts --fix, bun x tsc --noEmit and design-lint came back with nothing flagged, but I only looked at the tail of their output.

  • Head links: layout.ts emits <link rel="help" href="…"> for each help link pageLinks returns, straight after <meta charset>. For a public repository with reports open, those are /{o}/{n}/report, /api/v1/repos/{o}/{n}/reports and, where the owner opened contributions, /api/v1/contribute. The Link header is unchanged, and the head links no longer repeat later in the head.
  • JSON-LD: repoStructuredData in structured_data.ts adds a SoftwareSourceCode object to the repo page, including the empty-repo view. Its potentialAction list has the same URLs as CommunicateAction targets.
  • llms text: the generated /{o}/{n}/AGENTS.md now also names the JSON reports endpoint and /api/v1/contribute.
  • Not shown: a private repository, or one with reports closed, gets none of this. /api/v1/contribute is listed only when the owner has opened it.

I used rel="help", not rel="report", because help is what the existing Link header and muse-journey already use. report isn't a registered link relation, so I didn't add a second vocabulary.

I left the global /llms.txt repo listing alone. Adding two URLs to every line would swell it, and it already says /{owner}/{name}/report needs no account. A repo that ships its own AGENTS.md is served as written, so the new JSON and offer line only appears in the generated one.

The first push was refused by a pre-push hook that wants a "Try:" line in the commit message, so I amended the commit to include one.

commented

<!-- look-pages 0bf2843b96f5 --> Look pages for 0bf2843, from the gate:

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

A public repository's page now tells an outside agent how to report a problem and offer a change within its first 500 bytes. The same links appear in its JSON-LD and in its llms text. This update changes no code.

What changed: the gate's look-pages note had inferred 25 pages to picture, because src/web/doors_words.ts is imported by many routes. The change only shows on a public repository's page. I pushed an empty commit with a Looks: /trevato/forge line, which overrides the inferred list so only that page is pictured. I haven't run the look-pages gate on the new commit, so I don't know yet that it takes the override.

What I left alone: I didn't run bun test or tsc again, because no code changed after the earlier push. I disagree with the inferred list: doors_words.ts gained one word and no other page's output changed.

How to try it: open a public repository's page and view source. The report and offer links come first in the head.

🤖 Generated with Claude Code

commented

<!-- look-pages 3ca799e457d4 --> Look pages for 3ca799e, from the gate:

  • look pages (inferred): "Looks: /trevato/forge" is not a page of app.looks in forge.json; this pull changes src/web/doors_words.ts, src/web/layout.ts, src/web/pages/repo.ts and 1 more; the forge pictures / (src/web/doors_words.ts), /docs (src/web/doors_words.ts), /explore (src/web/doors_words.ts) and 22 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

I pushed an empty commit that answers both gate failures with the lines the gate accepts. I haven't re-run the gate or the tests here. Nothing was changed in src/tui/ or docs/features/, so the "both doors" failure stands or falls on that No door: line.

  • Both doors: the commit has a No door: line. The page's visible report and offer line already exists in the terminal. This pull adds only a <link rel="help"> in the head, JSON-LD, and llms text, so the page shows nothing new for the terminal to match. If the reviewer wants the terminal to carry the report and offer pointers too, I'd add them under src/tui/.
  • Look pages: my earlier Looks: /trevato/forge was invalid, because only paths listed in app.looks in forge.json are accepted. The commit now has a No look: line instead, since nothing visible changes.

I didn't change any code.

🤖 Generated with Claude Code

commented

I merged main into the branch and pushed it. The only conflict was the import lines in src/web/pages/repo.ts, and I kept both sides there. main added lowWallet to the wallet import, and this pull adds the repoStructuredData import.

bun x tsc --noEmit is clean. The three tests in test/muse-find.test.ts pass, and that file covers this change. I didn't run the rest of the suite, since the forge runs the full check on the push.

The pull itself is unchanged: a public repository's page names how to report a problem and offer a change within its first 500 bytes, in its JSON-LD and in its llms text. The gate lines from the earlier commits still stand: No door: (the terminal already shows the visible line) and No look: (only the head, JSON-LD and llms text change).

To try it, open a public repository's page and view source. The report and offer links come first in the head.

🤖 Generated with Claude Code

the crew's run was interrupted: restart, resumes on the next pass — cancelled
Changes requested — before the latest push

The change works as the issue asks, but two items on the checklist are missed. 1) Both doors: nothing in src/tui/ carries the report and offer pointers (the JSON reports endpoint and /api/v1/contribute), and there is no docs/features/<name>.md for this. A "No door:" commit line does not stand in for either. Add the pointers to the terminal's repository screen, where the page's visible report/offer line already has its terminal twin, and write the how-to in docs/features/, not README. 2) The private-repo test is vacuous. Its second assertion looks for the string application/ld+json">{"@context"... which the markup may never produce in that form, so it passes whether or not the JSON-LD leaks. Parse the page for any ld+json script and assert none has @type SoftwareSourceCode. Also add a test that a public repo with reports closed gets no doors and no JSON-LD, and one that without opened contributions /api/v1/contribute is absent. Smaller: the preview has no public repo at /trevato/forge (404), so I could not see the head links live; the test covers the first-500-byte claim. rel=help rather than rel=report is a sound choice. No design-system breakage: nothing visible is added.

commented

I've added the terminal pointers and the how-to, and replaced the private-repo test with a real JSON-LD assertion. tsc and the gate are clean, and the muse-find, tui-report and feature-orphans tests pass. I didn't run the full suite.

What changed

  • Terminal doors: a repository's : palette now has "How outsiders report or offer" (outsideDoorsCommands in src/tui/screens/report.ts, wired into the repo screen in workspace.ts). It shows a toast naming /owner/name/report and POST /api/v1/repos/owner/name/reports. It adds POST /api/v1/contribute only when outside contributions are open. A private repo, or one with reports closed, gets no row. I put it in the palette because the repo screen has no static line, so the toast is the terminal twin of the page's visible report/offer line.
  • Docs: docs/features/muse-test.md gains a "Where the doors are written" section covering the web and terminal doors and the test file. It's an existing feature file, so no README change and no new orphan row.
  • Private-repo test: it now parses every ld+json script on the page. It asserts there is none, and so none of type SoftwareSourceCode.
  • New tests:

- A public repo with reports closed has no doors in the first 500 bytes, none of the reports URL, and no JSON-LD. - A public repo without opened contributions has the report door but no /api/v1/contribute, in the HTML or in the JSON-LD targets. - The terminal row appears only where the page's doors do, and names the offer door only when contributions are open.

Left out: there's no live-preview check of the head links, since the preview has no public repo at /trevato/forge; the first-500-byte test covers that claim.

commented

I fixed the failing gate rule and pushed. The gate and tsc are clean, and the six tests in test/muse-find.test.ts pass. I didn't run the full suite.

The terminal-doors test in test/muse-find.test.ts used four as never casts. It now builds a real session and context with createForgeApp and a headless terminal. It then asserts the same things as before:

  • A public repo's row names the report door, the JSON reports endpoint and /api/v1/contribute.
  • A public repo without opened contributions has no offer door in its row.
  • A private repo, or one with reports closed, gets no row.

The gate still listed the old lines after I'd edited the file. It reads the pull's committed diff, so it only went quiet once I committed.

Approved

Approved. The asks from my last round (terminal door, how-to in docs/features, a real JSON-LD assertion for private repos, no as never casts) are met in the diff. The preview has no public repo to open, so I judged the head links, JSON-LD and llms line from the diff and test/muse-find.test.ts, which asserts all three doors in the first 500 bytes, in the JSON-LD targets and in AGENTS.md. The page has no new visible element, so the design principles are not engaged. Next: (1) Non-blocking: the head filter now runs on every page, so a small test that a non-repo page keeps its help links in the usual place would pin that. (2) Non-blocking: the : toast is easy to miss, so a static line on the terminal repo screen would be more discoverable.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs