NEC-386: Website: Product › Features, a read-only feedback board on nectenda.com #354

Merged
nectenda-agent merged 13 commits from worktree-nec-386-website-product-features-a-read-only-fee into main 2026-11-10 16:56:23 +00:00
Collaborator

Task: NEC-386 — https://projectron.nerchure.com/tasks/408

The feedback board's public, read-only pages on nectenda.com: /features (the list, with Sort and Filter as script-free

links) and /features/ (one idea with its comments), in the site's own shell, plus the plugin's "View on nectenda.com" link.

Every page is drawn from one snapshot of the public board (new GET /api/snapshot, computed at most every 10 s), kept at each Cloudflare location under one key: fresh for 60 s, with a 30 s grace while one request refreshes it in the background, behind a 15 s lease, and as a last good copy for a day, shown with its time when the board is down. So visitors' traffic cannot become the board's load; decided with the user after three reviews, each worked through (spec: docs/changes/NEC-386-features-board/spec.md). Other hosts (nectenda.pages.dev, previews) redirect to nectenda.com. HSTS joins _headers for the whole site.

Ride-along NEC-392: CI and the local gate now run site/'s own tests.

After merge, the user's steps are in docs/manual-testing.md: the Cloudflare rate-limiting rule, the status page push, and the live checks. /features shows its 'cannot be reached' text for the minutes between the site's deploy and the board's promotion.

Spec: docs/changes/NEC-386-features-board/spec.md

Also fixes NEC-392: Site tests never run on a pull request, only after merge in deploy-site.yml

Changelog

The Feedback page links to the board's new public, read-only pages at nectenda.com/features.

Task: NEC-386 — https://projectron.nerchure.com/tasks/408 The feedback board's public, read-only pages on nectenda.com: /features (the list, with Sort and Filter as script-free <details> links) and /features/<id> (one idea with its comments), in the site's own shell, plus the plugin's "View on nectenda.com" link. Every page is drawn from one snapshot of the public board (new GET /api/snapshot, computed at most every 10 s), kept at each Cloudflare location under one key: fresh for 60 s, with a 30 s grace while one request refreshes it in the background, behind a 15 s lease, and as a last good copy for a day, shown with its time when the board is down. So visitors' traffic cannot become the board's load; decided with the user after three reviews, each worked through (spec: docs/changes/NEC-386-features-board/spec.md). Other hosts (nectenda.pages.dev, previews) redirect to nectenda.com. HSTS joins _headers for the whole site. Ride-along NEC-392: CI and the local gate now run site/'s own tests. After merge, the user's steps are in docs/manual-testing.md: the Cloudflare rate-limiting rule, the status page push, and the live checks. /features shows its 'cannot be reached' text for the minutes between the site's deploy and the board's promotion. Spec: `docs/changes/NEC-386-features-board/spec.md` Also fixes NEC-392: Site tests never run on a pull request, only after merge in deploy-site.yml ## Changelog The Feedback page links to the board's new public, read-only pages at nectenda.com/features.
nectenda.com/features shows a count beside every status in its Filter menu.
The board had no public per-status count, so each page would have cost seven
board calls (the list plus six `?status=…&limit=1` totals), all from
Cloudflare's addresses and so all against one 300-a-minute read limit.

`GET /api/ideas` now carries `counts: [{ status, n }]`, counted over what
everyone can see, whatever the request's filters and whoever asks. A hidden
idea is not counted even in its author's answer, so the counts are one answer
the website can cache for every visitor (BOARD-015).

An array rather than a map keyed by status: a `planned` key reads as plan data
to privacy.test.ts's walker, and mutation-checking the map form showed it
failing there on `$.counts.planned`.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
/features lists the board's ideas, with Sort and Filter as <details> menus of
plain links, and /features/<id> shows one idea: status, author, date, total
votes, body, team response and comments, with "Vote in Obsidian" opening it in
the plugin. No script, no form, no cookie.

The frame is the site's own. build.mjs writes public/features.html through the
same page() and productNav() as every other page, with one marked region, and
a Pages Function (site/functions/features/, site/board/handler.mjs) fills that
region and nothing else. board.test.mjs holds every byte outside it to the
built shell, and the shell's header and footer to the roadmap's.

- Only fields the page names are read from the board, and every one is
  escaped: a fixture salted with per-plan counts, classes and voters shows none
  of them, and markup in any field arrives as text.
- Pages does not apply _headers to a Function's response, so the handler sends
  the same set, and the test fails if the two differ. HSTS joins _headers for
  the whole host, as the card asks.
- A page is cached for a minute at the edge, under one address per view. A
  board that is down, throttled, slow or unrecognisable gets the shell's own
  "cannot be reached" text as an uncached 503, never stale content.
- The Filter counts are optional. The site deploys as soon as this lands; the
  board gets `counts` only once CI promotes it. Running the Function in
  wrangler's runtime against the live board showed /features answering 503
  until the page stopped requiring them.
- Features is first under Product, in the header, the left menu and the status
  page's copy of the header.

packages/board/src/site-contract.test.ts holds the fixtures to a real board's
answers, key by key, so the site's tests cannot pass against a shape the board
no longer sends.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
The list's foot gains "View on nectenda.com", beside "Show more", as the agreed
design has it, opening https://nectenda.com/features in the browser. A unit
test also holds the plugin's deep-link parser to the two links the website's
"Vote in Obsidian" buttons send, and the e2e run checks the link in the real
Feedback page.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
The roadmap had the board under Considering and said there was no board, so
requests went to an inbox. It is now In progress: the server and the website
are live, and the plugin's Feedback page arrives with a release, after which it
can move to Shipped with that version. "Something missing?" links the board
and keeps hello@nectenda.com beside it.

privacy.md and go-to-market.md said the website half was still to come.
manual-testing.md gains the checks only Cloudflare and a browser can make, and
the spec records the plan as built.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
site/ is outside the pnpm workspace, so `pnpm test` never reaches its suites,
and ci.yml had no step for them: they ran only in deploy-site.yml, after a
merge, before the deploy. A pull request that broke the site merged green and
failed at its deploy, already on main. NEC-386's tests (the /features shell's
drift, no plan data on a page, the headers) would have gated the deploy and
never the merge.

The build job now runs `npm install && npm test` in site/, as deploy-site.yml
does; `npm install` because site/ has no lockfile.

Task: NEC-386
Also-fixes: NEC-392

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
gate-local.sh is ci.yml's build job in the same order, so a card finds out on
the Mac rather than on the runner. ci.yml gained the site's suites in the
previous commit; this keeps the two in step.

Task: NEC-386
Also-fixes: NEC-392

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
styles-contract.test.ts requires a stylesheet rule for every nectenda- class
the plugin adds, and the new link's class had none. It keeps "View on
nectenda.com" on one line in a narrow settings pane.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
- `fillShell` passed board text to String.replace as a replacement string,
  where `$&`, `$'` and `` $` `` mean "the match" and "what surrounds it". An
  idea whose body held `$x^2$`-style math pasted eight copies of the shell's
  head into its own. It cannot inject markup (the text stays escaped), but it
  broke the page's head and the rule that nothing outside the region changes.
  A function replacer now, and a test with each pattern in a title and body.
- A page was cached with `max-age=60` for the edge and the browser alike, so
  a browser could keep for a minute the copy the edge had already kept for one.
  Now `max-age=0, s-maxage=60`: the edge keeps it a minute and no browser
  keeps it at all. Checked in wrangler's runtime that the Cache API still
  holds it (five requests, two board reads).
- A shell that is not the shell, or any error while rendering, reached the
  visitor as Cloudflare's own 500 without the site's headers. It is a 503 with
  them now, checked before anything is filled.
- Tests the review showed could not fail: the five-second timeout (a board
  that never answers now has to be given up on), escaping and plan data over
  the whole page rather than only the region (an idea's own fields fill the
  head too), and the two functions/features/ files themselves.
- Two claims I had not checked. The rate limit is a known limit, not "far
  under": the number of distinct pages is the visitor's to choose, so a script
  can have the board refuse the site, and the spec says so. And _headers no
  longer says every subdomain sends its own HSTS; only feedback's Caddy does.

Each new rule was mutation-checked in both directions.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
nectenda.com/features read the board once per distinct page per minute, and
the visitor chooses the pages (`?page=2`, `3`, … and any idea id), so a
script could have run the board into its own rate limit and the page into a
503. Decided with the user: every page renders from one snapshot of the
public board instead, kept under one fixed key at the edge, so the board's
load no longer depends on the site's traffic or the addresses asked for.

`GET /api/snapshot` (snapshot.ts) holds every idea a signed-out reader may
see, with its visible comments, each sort's order as idea ids, and where each
merged idea went. It is the same for every caller, token or not, and is
computed at most once every 10 s, so any number of readers costs the database
one computation per window (BOARD-015, reworded from the per-list counts this
replaces, which leave /api/ideas). The sorts stay the board's: the snapshot's
orders come from the list's own ORDER BY, now `ORDER_BY` in ideas.ts, and each
ends on the id so ties come out in one order everywhere. privacy.test.ts walks
the snapshot with the other public routes; site-contract.test.ts holds the
website's new fixture to it.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
The Function now keeps one thing at each Cloudflare location: the board's
snapshot, fresh for 60 s and as the last good copy for a day. Every list,
sort, filter, page and idea is drawn from it, so the board is read at most
once a minute per location with visitors, whatever is asked for. In
wrangler's runtime, 50 requests across made-up addresses read the board once.

- The site filters and pages, but never sorts: it takes each sort's order from
  the snapshot, so Top and Trending mean what they mean in the plugin.
- When the board cannot give a usable snapshot, the page draws from the last
  good copy if the board made it under a day ago, judged by the copy's own
  time rather than the cache's, and opens with "this is how it stood at <time>
  UTC". Such a page is never kept, and an id an old copy does not hold is a
  503 rather than a 404, since it may have been posted since. With no copy at
  all, it is the shell's 503 as before. Checked in wrangler's runtime with the
  board stopped.
- A rendered page is never kept anywhere (max-age=0), so a page is never older
  than its snapshot; only the two copies are.
- An address that is not an id still never asks for a snapshot.

The Filter menu's counts come from the snapshot, so the earlier "counts are
optional" path is gone. The spec records the decision and the alternatives
weighed (a separate allowance for the site; a KV copy), the deploy-order gap
and the snapshot's size limit, and manual-testing.md gains the user's
rate-limiting rule (60 requests per 10 s per IP on /features*).

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
The second review found three ways visitors could still drive the board, each
verified: a failing board was asked again on every request (50 requests, 50
reads); every request at a copy's expiry asked until the new copy landed (40
concurrent, 40 reads); and the cache key carried the request's host, so
nectenda.pages.dev and each preview address kept copies of their own, or none
if the Cache API does nothing there. Decided with the user:

- Asking the board takes a 15 s lease, claimed in the worker before anything
  is awaited and then in the location's cache, and nobody else there asks
  until it lapses, whether the board answered or not.
- Past a minute, the lease holder refreshes in the background and visitors
  keep the copy they have, for a 30 s grace: at most about 90 s old without a
  note. Each worker also keeps the parsed copy, so most requests read neither
  the cache nor the board, and parse nothing.
- Every key is under the site's own origin, and /features on any host but
  nectenda.com (localhost and 127.0.0.1 aside) answers 301 there.
- The stale note is one neutral sentence, true whether the board is down or a
  refresh is still running.

In wrangler's runtime: 60 requests, 20 of them concurrent, read a healthy board
once; 60 requests read a failing board once; nectenda.pages.dev redirected.

Also found while making this: a copy stamped a second in the future by a board
clock ahead of Cloudflare's was thrown away as unusable, which would have left
everyone but the lease holder with a 503. Ages now never count below zero.
And from the same review: the snapshot lists only merges into ideas everyone
can see, a page past the end says so rather than "no ideas match", and stale
idea pages and redirects are tested as never kept. Each rule was mutation-
checked; the spec and manual-testing.md say what each new part costs and
what remains best-effort (the cache may evict early).

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
The third review, of the lease commit, found no way past the lease, but five
ways it held up worse than claimed, each reproduced:

- Ages counted from the board's own `at`: a board clock an hour ahead pinned
  its copy as current for the hour, and one behind showed a fresh answer as
  old. Every copy now carries when this site received it, by Cloudflare's
  clock, into the cache too, and every age counts from that.
- A failed cache.match or cache.put became a 503, and failing puts stopped the
  lease from ever being taken again. Every cache call is now guarded: a failed
  read is a miss, a failed lease read falls back to the worker's own lease, and
  a failed write still gives the page its copy.
- Once a worker's copy was past a minute, every request re-read and re-parsed
  the cache (50 requests, 50 reads in an outage). Each worker now looks at
  most once per lease.
- A copy found only in the last good slot was shown with the note even when
  it was half a minute old. Whether a page carries the note is now decided by
  the copy's age alone.
- Nothing tested that the background refresh is handed to waitUntil or that
  the visitor does not wait for it: three mutations survived. A board that
  answers only when the test says now proves both, and that the refresh lands.

Also: [::1] counts as local development, and the spec now says that
`wrangler pages dev` runs one worker, so the runtime checks show the worker's
own lease and the lease between workers rests on the Cache API, first seen
for real in production. Each rule mutation-checked.

Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
Drop a test constant the receipt-time change left unused
All checks were successful
Release note / release-note (pull_request) Successful in 20s
CI / build (pull_request) Successful in 4m36s
CI / e2e (pull_request) Successful in 17m24s
CI / promote (pull_request) Has been skipped
5b720c4692
Task: NEC-386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaXPLDwMdRRrgpAUyK
cruelacid force-pushed worktree-nec-386-website-product-features-a-read-only-fee from 5b720c4692
All checks were successful
Release note / release-note (pull_request) Successful in 20s
CI / build (pull_request) Successful in 4m36s
CI / e2e (pull_request) Successful in 17m24s
CI / promote (pull_request) Has been skipped
to 8a8ee4d720
All checks were successful
Release note / release-note (pull_request) Successful in 16s
CI / build (pull_request) Successful in 5m47s
CI / e2e (pull_request) Successful in 17m12s
CI / promote (pull_request) Has been skipped
Deploy site / deploy (push) Successful in 1m3s
CI / build (push) Successful in 5m2s
CI / e2e (push) Successful in 17m14s
CI / promote (push) Successful in 43s
2026-11-10 16:38:19 +00:00
Compare
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Nectenda/nectenda!354
No description provided.