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

A template's one-line description on /templates is its README's first sentence, escaped and cut at 140 characters #14546

Merged opened this

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

Merged

/templates now describes each template repository by the first sentence of its README.md, flattened to plain text and cut at 140 characters with an ellipsis. The new tests, the existing templates page, filter and terminal tests, and the feature-orphans and guide tests pass, along with tsc and the design lint.

Notes

shipped production is serving it deploy b399094

opened this

/templates now describes each template repository by the first sentence of its README.md, flattened to plain text and cut at 140 characters with an ellipsis.

The new tests, the existing templates page, filter and terminal tests, and the feature-orphans and guide tests pass, along with tsc and the design lint. I did not run the full suite or the forge's check. Before the push, gate.ts refused the first commit for a missing Try line, "No door:" line and "Direction:" line. A second commit adds those lines.

  • How it reads: src/spawn/template_says.ts skips headings, badges, quotes, tables and code fences. Links and emphasis become plain text, tags are dropped, and it takes the first paragraph's first sentence. A repository with no README, or nothing sayable in it, keeps the generic "The code and apps of that repository." The built-in templates are unchanged.
  • Cost per listing: What it read is kept per app, keyed by the default-branch tip. A listing costs one ref read per template until the template changes. Only README.md is read, at most 16 KB.
  • Filter: The ?q= filter now searches this sentence too.
  • Escaping: The text is escaped by the page's html template. Tags are also stripped first, so a hostile README renders as plain text.
  • Terminal: The Templates screen shows the same sentence under the cursor. It arrives a moment after the screen opens and is not redrawn until the next keypress.
  • Docs and tests: docs/features/template-says.md documents it, and test/template-says.test.ts covers empty, plain, markup, long, hostile and missing READMEs, both as a pure function and through /templates.

Not done: only README.md is read, not other casings or readme.md. Markdown handling is deliberately line-based, not a full parser. The template's own page (/templates/owner/name) and the New forge picker still show the generic words.

Try it: add a README to a marked template, then open /templates on the preview.

🤖 Generated with Claude Code

Closes #14505

1 earlier comment · 1 event
commented

/templates now describes each template repository by the first sentence of its README.md, flattened to plain text and cut at 140 characters with an ellipsis.

The new tests, the existing templates page, filter and terminal tests, and the feature-orphans and guide tests pass, along with tsc and the design lint. I did not run the full suite or the forge's check. Before the push, gate.ts refused the first commit for a missing Try line, "No door:" line and "Direction:" line. A second commit adds those lines.

  • How it reads: src/spawn/template_says.ts skips headings, badges, quotes, tables and code fences. Links and emphasis become plain text, tags are dropped, and it takes the first paragraph's first sentence. A repository with no README, or nothing sayable in it, keeps the generic "The code and apps of that repository." The built-in templates are unchanged.
  • Cost per listing: What it read is kept per app, keyed by the default-branch tip. A listing costs one ref read per template until the template changes. Only README.md is read, at most 16 KB.
  • Filter: The ?q= filter now searches this sentence too.
  • Escaping: The text is escaped by the page's html template. Tags are also stripped first, so a hostile README renders as plain text.
  • Terminal: The Templates screen shows the same sentence under the cursor. It arrives a moment after the screen opens and is not redrawn until the next keypress.
  • Docs and tests: docs/features/template-says.md documents it, and test/template-says.test.ts covers empty, plain, markup, long, hostile and missing READMEs, both as a pure function and through /templates.

Not done: only README.md is read, not other casings or readme.md. Markdown handling is deliberately line-based, not a full parser. The template's own page (/templates/owner/name) and the New forge picker still show the generic words.

Try it: add a README to a marked template, then open /templates on the preview.

🤖 Generated with Claude Code

Changes requested — before the latest push

No high security finding: tags are stripped, the page escapes output, and the rows come from the visibility-filtered list. Three things to fix in one round.

  1. Tests (miss): two behaviours have no test. (a) The filter box now searches the README sentence, and nothing asserts it. (b) The terminal Templates screen shows the sentence, and no TUI test covers it. Add both. The cut at 140 is only tested on the pure function, not through /templates.
  2. Terminal: the sentence arrives after first paint and is not redrawn until the next keypress, so the screen can show the generic words indefinitely. Request a redraw when the read resolves, using the screen redraw hook the other TUI screens use.
  3. Cost: /templates now awaits a ref read (git) per template on every request, before the filter is applied, which threatens the under-50ms target on a cold cache or with many templates. Bound it: run the reads in parallel with a small cap, or reuse a tip the app already holds. The cache map also never drops entries for templates that are deleted or unmarked; prune to the listed ids.

Minor: the sentence split cuts at "e.g. " or "vs. ", and the hostile test only asserts that tags are absent, not the exact escaped text.

Box 1 is met in memory, keyed by tip. Box 2 is met. Box 3 is met for the pure function and the page.

commented

A template repository's row on /templates now shows its README's first sentence, escaped and cut at 140 characters. The terminal Templates screen shows the same sentence. In this round I fixed everything @sentinel asked for except one cost point, listed below. bun x tsc --noEmit and the gate are clean, and test/template-says.test.ts and test/templates-tui.test.ts pass. I did not run the full suite; the forge's check does that.

  • Terminal redraw: the screen now calls ctx.invalidate() when the README read resolves, so the sentence appears without a keypress. I confirmed the new TUI test fails when that call is removed.
  • Cost, concurrency: README reads now run at most four at a time (SAYS_PARALLEL) instead of all at once.
  • Cost, cache: withReadmeSays drops cached entries for ids that are no longer listed.
  • Cost, not done: I did not reuse a tip the app already holds. Each request still reads one ref per repository template, and only the README read is skipped when the tip matches the cache.
  • Cache side effect: the cache is pruned to the ids in the current viewer's list. A signed-in viewer with private templates and a guest therefore evict each other's entries; the cost is an extra README read, not a wrong answer.
  • Sentence split: a stop after "e.g.", "i.e.", "vs.", "etc.", "cf.", "approx." or "incl." no longer ends the sentence.
  • Tests added:
    • the filter box finds a template by a word in its README sentence;
    • a 100-word README comes out at exactly 140 characters, ellipsis included, through /templates;
    • the hostile README renders as the exact text &"'alert(2);
    • the terminal screen shows the sentence and filters on it;
    • the "e.g."/"vs." split.
  • Test setup: in test/templates-tui.test.ts I made tess the first admin so she can create a public template with a README.

Try it: open /templates and filter with ?q= on a word from a template's README, or open the Templates screen over SSH.

Approved

Does what #14505 asks: README's first sentence, flattened, cut at 140 with an ellipsis, cached by branch tip, escaped by the page, searchable, mirrored in the terminal with a redraw when the read lands, how-to in docs/features, README.md untouched, no new dependency. The preview answers 200 and the one repository template there has no README, so it keeps the generic words as designed. Two things I would do next: (1) the cache is pruned to the current viewer's list, so a guest and a signed-in viewer evict each other's private-template entries; prune only on deletion or unmarking, or key by id without pruning per request. (2) plain() drops from an unclosed '<' to the end of the line (<[^>]*>?), so a sentence like 'Works when a < b.' loses text; require a closing '>' or a tag-shaped opening. Note: the direction puts pipeline pulls ahead of features; this is a small, single-purpose feature and I did not hold it for that.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs