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

The maintenance board filters findings by severity with plain links that survive a reload #14567

Merged opened this

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

Merged

/maintenance now takes ?level=needs-you or ?level=fyi and narrows the board to that severity. Any other value shows everything, as does no value. The new test file and the existing maintenance page, filed, stale, merged, dismiss and calm tests pass locally, and the type check, gate and design-lint were clean.

Notes

shipped production is serving it deploy 3dfbd46

opened this

/maintenance now takes ?level=needs-you or ?level=fyi and narrows the board to that severity. Any other value shows everything, as does no value. The new test file and the existing maintenance page, filed, stale, merged, dismiss and calm tests pass locally, and the type check, gate and design-lint were clean. A broader scripts/fast.ts run timed out in the sandbox, so I did not wait for it.

What changed

  • The page had no explicit severity, so I defined two levels from what it already marks as needing a person:
    • Needs you: the Duties fold when a duty is overdue or paused, stale pulls, merged branches, preview data, the maintenance state while maintenance is on, and a failed last return.
    • For information: the other sections, such as Budgets and the write pause.
  • A strip of plain links (All N · Needs you N · For information N) sits under the status line. Each link has its count, the current one is bold with aria-current, and there is no JavaScript.
  • The default view still shows every section.
  • The filter is src/maintenance/level.ts, and src/web/pages/maintenance.ts only gains the strip and a list of sections tagged with their level.
  • Tests in test/maintenance-level.test.ts cover each level narrowing, the default view, an unknown value showing everything, and markup in the value not being echoed.

Left out

  • Findings inside a fold are not filtered individually.
  • The status line is always shown.
  • The "Try:" empty commit is there only because the pre-push hook requires one.

To try Sign in as an admin and open /maintenance, then follow the strip links or open /maintenance?level=needs-you.

Closes #14544

19 earlier comments · 3 events
commented

/maintenance now takes ?level=needs-you or ?level=fyi and narrows the board to that severity. Any other value shows everything, as does no value. The new test file and the existing maintenance page, filed, stale, merged, dismiss and calm tests pass locally, and the type check, gate and design-lint were clean. A broader scripts/fast.ts run timed out in the sandbox, so I did not wait for it.

What changed

  • The page had no explicit severity, so I defined two levels from what it already marks as needing a person:
    • Needs you: the Duties fold when a duty is overdue or paused, stale pulls, merged branches, preview data, the maintenance state while maintenance is on, and a failed last return.
    • For information: the other sections, such as Budgets and the write pause.
  • A strip of plain links (All N · Needs you N · For information N) sits under the status line. Each link has its count, the current one is bold with aria-current, and there is no JavaScript.
  • The default view still shows every section.
  • The filter is src/maintenance/level.ts, and src/web/pages/maintenance.ts only gains the strip and a list of sections tagged with their level.
  • Tests in test/maintenance-level.test.ts cover each level narrowing, the default view, an unknown value showing everything, and markup in the value not being echoed.

Left out

  • Findings inside a fold are not filtered individually.
  • The status line is always shown.
  • The "Try:" empty commit is there only because the pre-push hook requires one.

To try Sign in as an admin and open /maintenance, then follow the strip links or open /maintenance?level=needs-you.

commented

<!-- look-pages f6c5d2f10c3b --> Look pages for f6c5d2f, from the gate:

  • look pages (inferred): this pull changes src/web/pages/maintenance.ts; the forge pictures /system (src/web/pages/maintenance.ts), /maintenance (src/web/pages/maintenance.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

<!-- look-pages 303ef6b1a5e8 --> Look pages for 303ef6b, from the gate:

  • look pages (inferred): this pull changes src/web/pages/maintenance.ts; the forge pictures /system (src/web/pages/maintenance.ts), /maintenance (src/web/pages/maintenance.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

The look-pages comment is informational and asks for no change. The inferred pages, /maintenance and /system, are the ones this pull touches, so I made no override and pushed nothing new.

What changed: /maintenance can be filtered by level with plain links, ?level=needs-you or ?level=fyi. Each filter shows its count and marks the current one. The filter is part of the URL, so it survives a reload and can be shared. The page is server-rendered, so there is no added JavaScript. Gate lines for the level filter are included.

What I left out: there is no client-side filtering or remembered filter state. The level comes only from the URL.

How to try it: open /maintenance?level=needs-you, then follow the "For information" link. Run bun test for the coverage.

commented

I merged main into the branch and pushed it (1ff698896). The only conflict was in src/web/pages/maintenance.ts.

main had added a findings section (findingsFold) and a findings.ts import. My branch had turned the board's sections into a list tagged by level. I kept both imports and added the findings section to the list as an "fyi" entry, next to Budgets and the write-pause fold.

I ran six maintenance test files covering the level filter, findings, the page and the stale, merged and pause views: 28 pass, 0 fail. bun x tsc --noEmit is clean and bun scripts/gate.ts --fix changed nothing.

I did not run the full set scripts/fast.ts named for this diff. It listed 2212 of 3814 files, with an estimated run of about 187 minutes, so I picked the six files myself. The forge's own check runs the whole suite on the push.

commented

<!-- look-pages 1ff69889619b --> Look pages for 1ff6988, from the gate:

  • look pages (inferred): this pull changes src/web/pages/maintenance.ts; the forge pictures /system (src/web/pages/maintenance.ts), /maintenance (src/web/pages/maintenance.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

The gate comment from @trevato only lists which pages the forge will picture (/system and /maintenance, both from src/web/pages/maintenance.ts). It asks for no change, so I changed nothing and pushed nothing.

The inferred pages are the right ones, so I'm leaving the default instead of adding a Looks: or No look: line to a commit message.

What the pull does: /maintenance filters its sections by level with plain links (?level=needs-you or ?level=fyi). A strip shows the count for each level and marks the current one, and the filter survives a reload. The merge with main put the new findings section under "fyi". Six maintenance test files pass (28 tests) and tsc is clean; I skipped the full suite scripts/fast.ts named for this diff, as it would take hours here.

[
  {"go": "/maintenance", "look": "The level strip above the sections", "expect": "It shows counts for needs-you and fyi, and no filter is marked as current"},
  {"go": "/maintenance?level=needs-you", "look": "Sections shown and the strip", "expect": "Only the sections that need a person appear, and needs-you is marked as current"},
  {"go": "/maintenance?level=fyi", "look": "The Findings and Budgets sections", "expect": "They appear, and the sections that need a person do not"}
]
Changes requested — before the latest push

The filter works and is plain links, but this head has misses against the list. Fix first: the strip is hand-rolled markup (inline links separated by a literal middle dot, bare strong for the current one) instead of a named component from docs/DESIGN.md, and its tap targets are text-sized, which is hard to hit with a thumb at 360px. Also needed: (1) the terminal door has no level filter and there is no docs/features/ how-to for it, which the both-doors rule requires; (2) counts count sections, not findings, so 'Needs you 1' can sit over a fold holding many rows, and the status line says 'Needs you' regardless of the filter, which reads as a contradiction; (3) a level with zero sections renders an empty page with no sentence saying so; (4) tests: the fyi test never asserts the needs-you sections are gone, and the needs-you test never asserts a needs-you section is present (seed a stale pull or overdue duty), so 'each level narrows' is only half proven; (5) a section's level flips with state (Duties, Last return, maintenance-prepare), so the same fold jumps between filters; say why in the code or keep it fixed. Box 1 is met; boxes 2 and 3 are not.

commented

/maintenance?level=needs-you and ?level=fyi now narrow the board with the forge's own seg() control, and I've addressed each point except the terminal's treatment of paused duties, which I left as a gap. I ran tsc, gate.ts --fix, design-lint and 28 tests across the maintenance-level, maintenance-page, maintenance-calm, doorless and attention files. All pass. Two other tests that cover .seg styling (test/components-palette-focus.test.ts, test/apps-archived.test.ts) passed in an earlier run, before the final test edit.

What changed:

  • Strip: it is seg() with All, Needs you and For information, with no middot or bare strong. A .levels rule makes each link 44px tall at 480px wide or less, or on a coarse pointer. It is described in a new docs/design/areas/maintenance.md.
  • Counts: I dropped them. A section count reads as a finding count, and a true row count would mean counting inside every fold, so the links carry words only.
  • Status line: the "For information" view leaves it out, so "Needs you" no longer sits over the calm sections.
  • Empty level: it renders "Nothing here needs you." (or "Nothing here to read." under For information).
  • Terminal door:
    • Filter: l on the Maintenance screen cycles all, Needs you and For information, via nextLevel in src/maintenance/level.ts.
    • Gap: there, overdue duties count as needing you but paused ones are not listed, which differs from the page.
    • Docs: docs/features/maintenance.md has the how-to.
  • Level flips: I kept the flips and explained them in a comment in src/web/pages/maintenance.ts. Duties, the state fold and Last return follow the status line's rule, so a section moves between filters only when it starts or stops needing a person.
  • Tests:
    • A seeded stale pull appears under needs-you and not under fyi.
    • The fyi view asserts the needs-you section is gone.
    • The needs-you view asserts the empty sentence and that the calm sections are gone.
    • The terminal filter has its own test.
    • The old test for countLevels went with the counts.

I did not run the full suite: scripts/fast.ts named 2212 of 3814 test files for this diff, so I picked the ones that cover the change. The forge runs the full check on push.

[
  {"go": "/maintenance", "look": "The strip under the status line", "expect": "A segmented control with All marked current, no counts and no middots"},
  {"go": "/maintenance?level=needs-you", "look": "The page body", "expect": "Only the sections that need a person, or the sentence 'Nothing here needs you.'"},
  {"go": "/maintenance?level=fyi", "look": "The top of the page", "expect": "No status line, and only the calm sections"},
  {"go": "/maintenance", "ask": "At 360px wide, can each strip link be hit with a thumb?", "look": "Link height", "expect": "Each link is about 44px tall"}
]
commented

<!-- look-pages 9cdecb703795 --> Look pages for 9cdecb7, from the gate:

  • look pages (named): this pull changes src/web/pages/maintenance.ts, src/web/style/components.ts; a commit names /maintenance
commented

The gate's as never rule is fixed and pushed as f0f6d659a; I haven't seen the forge's re-run of the check yet.

test/maintenance-level.test.ts no longer casts to never when it calls nextLevel. It now builds a typed list of Level | undefined and maps over that, so the type checker sees the real input. The only edit besides that is importing the Level type.

Locally, bun x tsc --noEmit is clean and the 7 tests in test/maintenance-level.test.ts pass. bun scripts/gate.ts comes back clean after the commit; the gate only judges committed lines, so it kept reporting the old line until I committed. I did not run the rest of the suite; the forge runs the full check on push.

The gate's note about a long comment line in src/tui/screens/maintenance.ts is informational, and the nightly rewrap on main handles it.

commented

No code change was needed for this feedback. The look-pages comment is the gate naming /maintenance as the page a reviewer should look at; it isn't a failure. The pull description needs a review block, so here it is.

The maintenance board now filters findings by severity with plain links (/maintenance?level=needs-you, ?level=fyi, or none for all). The current choice is marked with aria-current="page", and a reload keeps it because the level lives in the URL. An unknown level shows everything. A level with no sections says so in one sentence ("Nothing here needs you."). The seg() links are thumb-sized and show no section counts. The change also adds a terminal door and a how-to. The level parser is src/maintenance/level.ts, and the tests are in test/maintenance-level.test.ts. The latest push (f0f6d659a) fixes the gate's as never rule in that test.

I did not add client-side JavaScript filtering or remember the level between visits, so the filter is just a link.

To try it, open /maintenance on the preview at https://lab--14567--forge-trevato-apps.open-platform.sh, signed in as an admin.

[
  {"go": "/maintenance", "look": "The row of level links above the findings: All, Needs you, For information, as one segmented control with no section counts.", "expect": "All is the current link; every section is shown; nothing shifts when the page loads."},
  {"go": "/maintenance?level=fyi", "look": "The control and the sections below it.", "expect": "For information is marked current; only calm sections show; stale pulls and the status section are gone."},
  {"go": "/maintenance?level=needs-you", "look": "The body under the control when no finding needs the person.", "expect": "One sentence, \"Nothing here needs you.\", and no budgets or prepare sections."},
  {"go": "/maintenance?level=bogus", "look": "The control and the sections.", "expect": "Same as /maintenance: All is current and every section shows.", "ask": "Is falling back to All the right answer for a level nobody offers?"}
]
commented

I merged main into the branch, resolved the three conflicts keeping both sides, and pushed as 77a621d4f. bun x tsc --noEmit is clean and 253 tests pass across the 40 maintenance test files, including the level and quiet tests. I haven't seen the forge's check on this push yet.

  • docs/features/maintenance.md: both sections kept, the level-filter paragraph and the quiet-a-finding section from main.
  • src/web/pages/maintenance.ts: the "Quieted" section from main is now one of the filtered sections, marked as for information. A finding put aside for a day is something to read, not something waiting on a person, so it shows under "All" and "For information" but not under "Needs you".
  • src/tui/screens/maintenance.ts: the l level cycle and the z/b quiet keys now work together.
    • The quieted list shows in the "All" and "For information" views.
    • The numbered "Findings (z quiets one)" list shows in "All" and "Needs you" but not "For information", for the same reason.

bun scripts/gate.ts --fix reported that it rewrapped comments in one file, but afterwards there was nothing to commit, so the merge commit already carries them.

commented

<!-- look-pages 77a621d4f110 --> Look pages for 77a621d, from the gate:

  • look pages (named): this pull changes src/web/pages/maintenance.ts, src/web/style/components.ts; a commit names /maintenance
commented

I restored test/check-times.test.ts to match main and pushed as b932f615d; I haven't seen the forge's check on this push yet.

The earlier bun scripts/gate.ts --fix had rewrapped a comment on line 115 of that file, which this pull didn't write. Restoring it removes that file from the pull's diff, which was the gate's complaint.

bun scripts/gate.ts and bun x tsc --noEmit are clean locally. I didn't re-run the tests, since only a comment in a test file the pull doesn't change was reverted.

commented

<!-- look-pages b932f615dbda --> Look pages for b932f61, from the gate:

  • look pages (named): this pull changes src/web/pages/maintenance.ts, src/web/style/components.ts; a commit names /maintenance
commented

The look-pages note is the gate saying it will screenshot /maintenance. It asks for no code change, so I changed nothing and pushed nothing. I did not re-run bun test or tsc this turn. The review block below is what a page change owes.

The maintenance board can be narrowed by severity with a plain ?level= link. The strip of links sits above the sections and is rendered on the server. The chosen level is read from the URL, and an unknown value falls back to the full board. A level with nothing in it shows "Nothing here needs you." or "Nothing here to read." The filter needs no JavaScript and survives a reload. The code is in src/web/pages/maintenance.ts, src/maintenance/level.ts and src/web/style/components.ts.

I chose not to save the chosen level in a cookie or in state. The link is the state.

To try it, open /maintenance on the preview and follow each link in the level strip.

[
  {"go": "/maintenance", "look": "The level strip above the sections: the full board plus one link per level, with the current one marked", "expect": "All sections show, and the strip's first link is marked current"},
  {"go": "/maintenance?level=needs-you", "look": "Only the sections that need a person, and the strip's current marker", "expect": "Quieter sections are gone, 'Needs you' is current, and the page does not shift when switching levels"},
  {"go": "/maintenance?level=bogus", "look": "The whole board", "expect": "An unknown level is ignored and the full board renders, with no error"},
  {"go": "/maintenance?level=needs-you", "look": "Reload the page", "expect": "The same filtered view comes back, because the URL carries it", "ask": "Is a level with nothing in it (the empty line) clear enough?"}
]
Changes requested — before the latest push

The filter works, is server-rendered, validates ?level= against a closed list and escapes everything; no security finding. Three changes, in this order:

  1. Both doors disagree (src/tui/screens/maintenance.ts, overdue = loud.filter(d => d.overdue)): the page puts a paused duty under Needs you, the terminal lists neither paused nor... anything for it. The PR admits this gap. Close it: include paused duties in the terminal's needs-you set (or derive the page's and terminal's section level from one shared function in src/maintenance/level.ts, so the rule is written once and cannot drift). The terminal test only checks the empty case and fyi.length > 0; add one that seeds an overdue duty and asserts it appears under needs-you and not under fyi.
  2. Principle 1 (nothing explains itself twice): on ?level=needs-you with nothing waiting, the status line says "Healthy Nothing needs you." and the page then adds "Nothing here needs you." Show one sentence: hide the status line when the empty line is shown, or drop the empty line when the status line is the same sentence.
  3. Issue box 2 asks for links with counts. The head drops them on purpose (counts of sections would read as findings). Either give a true count (rows per level) or edit the issue box; as it stands the box is not met. Also the test title "carries the level links with counts" is wrong for what it asserts; rename it.

Smaller: while maintenance is on, the "maintenance-says" paragraph and End-maintenance button show in every view, including For information, which is the calm view; keep them only where needs-you applies or in All.

commented

/maintenance can be narrowed with ?level=needs-you or ?level=fyi. These are plain server-rendered links that survive a reload. The current link is marked, an unknown value shows the whole board, and markup in the value is never echoed. This push handles sentinel's review:

  • The page and the terminal agree. Which level a section sits at is now decided in one place, src/maintenance/level.ts (dutiesLevel, stateLevel, returnLevel), and both use it. A paused duty now shows under needs-you in the terminal, as it already did on the page. The terminal's all view lists paused duties too, so it contains everything either level shows. An empty For information view in the terminal now says "Nothing here to read." instead of "Nothing here needs you."
  • Said once. On Needs you with nothing waiting, the status line ("Healthy · Nothing needs you.") is the only sentence. The separate empty line now appears only on For information, where the status line is hidden.
  • Counts. The Needs you link shows the real number of things waiting: overdue and paused duties, stale pulls, merged branches, preview data, maintenance being on, and a failed return. The For information link has no number on purpose, because a count of things to read is not something to act on. That only half meets the second checkbox of #14544. I did not edit the issue, so a person should decide whether to accept this or reword that checkbox. I renamed the test title that wrongly claimed counts.
  • Calm view. While maintenance is on, the "maintenance-says" sentence and the End maintenance button no longer appear on For information.

New tests in test/maintenance-level.test.ts:

  • the shared rule for each level;
  • an overdue duty and a paused duty appear under needs-you and not under fyi, in the terminal and on the page;
  • the count is 0 on an empty board and 1 with one stale pull;
  • the calm view hides the End maintenance button.

The type check and the design lint pass, and all 348 maintenance, terminal-maintenance and page-budget tests pass. scripts/fast.ts named 2,242 test files for this diff (about 190 minutes), so I picked those suites myself instead.

[
  {"go": "/maintenance", "look": "The level strip under the status line", "expect": "All is marked current; Needs you has a number badge; For information has none"},
  {"go": "/maintenance?level=needs-you", "look": "The sentences on the page when nothing waits", "expect": "Only the status line says 'Nothing needs you.'; there is no second empty line, and the badge reads 0"},
  {"go": "/maintenance?level=fyi", "look": "Status line, maintenance sentence and End maintenance button", "expect": "None of them show; the calm sections (Budgets, Findings) do"},
  {"go": "/maintenance?level=needs-you", "look": "Pause a duty from the Duties fold, then reload", "expect": "Duties now sits under Needs you, the badge counts it, and the filter is still applied after the reload", "ask": "Should For information carry a count too, or should the issue's 'links with counts' checkbox be reworded?"}
]

🤖 Generated with Claude Code

commented

<!-- look-pages 8ede399ae324 --> Look pages for 8ede399, from the gate:

  • look pages (named): this pull changes src/web/pages/maintenance.ts, src/web/style/components.ts; a commit names /maintenance
commented

The gate's note doesn't ask for a change. It reports that the look pages were chosen as named: a commit names /maintenance and the diff touches src/web/pages/maintenance.ts and src/web/style/components.ts. /maintenance is the right page to picture, and the check on 8ede399 is green. I pushed nothing new; the description below is the current one.

---

/maintenance now takes ?level=needs-you or ?level=fyi and narrows the board to that severity. Any other value, or no value, shows everything. The terminal's maintenance view uses the same rule, so the page and the terminal agree.

What changed

  • One rule. src/maintenance/level.ts decides each section's level, and both the page and the terminal call it.
    • Needs you: overdue or paused duties, stale pulls, merged branches, preview data, maintenance being on, and a failed last return.
    • For information: everything else, such as Budgets and the write pause.
  • Level strip. A strip of plain links (All · Needs you · For information) sits under the status line. The current one is bold with aria-current, and there is no JavaScript. .levels is written up in docs/design/areas/maintenance.md: on a coarse pointer or at 480px each link is 44px tall.
  • Counts. The Needs you link shows the real number of things waiting. The For information link has no number on purpose, because a count of things to read is not something to act on. That only half meets the "links with counts" checkbox in #14544, so a person should decide whether to accept this or reword the checkbox.
  • Said once. With nothing waiting, Needs you shows only the status line ("Nothing needs you."). The separate empty line appears only on For information, where the status line is hidden.
  • Calm view. On For information, the status line, the maintenance sentence and the End maintenance button are hidden.

Left out

  • Findings inside a fold are not filtered one by one.

Tests

  • test/maintenance-level.test.ts covers:
    • each level narrowing the board, the default view, and an unknown value showing everything;
    • markup in the value not being echoed back;
    • overdue and paused duties appearing under Needs you, in the terminal and on the page;
    • the count being 0 on an empty board and 1 with one stale pull;
    • the calm view hiding End maintenance.
  • The type check, design lint and the maintenance, terminal-maintenance and page-budget suites pass.
  • scripts/fast.ts named 2,242 files for this diff, too many to run here, so I chose these suites myself.
[
  {"go": "/maintenance", "look": "The level strip under the status line", "expect": "All is marked current; Needs you has a number badge; For information has none"},
  {"go": "/maintenance?level=needs-you", "look": "The sentences on the page when nothing waits", "expect": "Only the status line says 'Nothing needs you.'; there is no second empty line, and the badge reads 0"},
  {"go": "/maintenance?level=fyi", "look": "Status line, maintenance sentence and End maintenance button", "expect": "None of them show; the calm sections (Budgets, Findings) do"},
  {"go": "/maintenance?level=needs-you", "look": "Pause a duty from the Duties fold, then reload", "expect": "Duties now sits under Needs you, the badge counts it, and the filter is still applied after the reload", "ask": "Should For information carry a count too, or should the issue's 'links with counts' checkbox be reworded?"}
]

Closes #14544

🤖 Generated with Claude Code

Approved

Sentinel's asks are met. (1) The page and the terminal now share dutiesLevel, stateLevel and returnLevel in src/maintenance/level.ts. Paused duties show under Needs you in both, and a test seeds an overdue and a paused duty. (2) The sentence is said once: the empty line shows only on For information, where the status line is hidden. (3) The Needs you link carries a real count, and the test title is fixed. (4) The calm view hides the maintenance-says sentence and the End maintenance button. The filter is server-rendered, works without JavaScript, validates against a closed list, and does not echo markup. The 44px targets are in place, and the doc is in docs/features, not the README.

Two things to do next:

  1. Non-blocking: the docs say 'no counts' but the code now shows a count on Needs you. Fix docs/design/areas/maintenance.md and docs/features/maintenance.md to say Needs you carries the number of things waiting and For information has none.
  2. Non-blocking: box 2 ('links with counts') is only half met, since For information has no count. A person should accept that or reword the box.
commented

Left #14544 open: 1 unticked item remain (Links with counts, current marked, no JavaScript; the default view is unchanged.).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs