dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 6 Packages Projects Releases Wiki Activity

feat: preview sorted storage usage bars (#3867)

Browse Source
This commit is contained in:
Carlos Florêncio
2026-09-23 13:45:37 +01:00
committed by GitHub
parent 9944354518
commit d3db4c7279
30 changed files with 2122 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/storage-analysis-presentation/plan.md
+249
View File
@@ -0,0 +1,249 @@
---
created: 2026-09-22
status: implemented
requirements:
- REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-003
- REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-005
system_design:
- ../../specs/system-page/system-design/storage-analysis-presentation.md
legacy_specs: []
---
# Implementation Plan: Storage analysis presentation
## Overview
Deliver concise temporary-folder timeout feedback and relative usage bars inside the existing Storage accordion.
The work orders were sequential because both changed the same resource projection and component tests.
The implementation and verification evidence are recorded below.
- [Requirements](../../specs/system-page/requirements/storage-maintenance.md): 003.10 and requirement 005.
- [System design](../../specs/system-page/system-design/storage-analysis-presentation.md).
- [Existing temporary-storage decision](../../decisions/2026-09-11-temporary-storage-visibility-policy.md).
Confirmed intent comes from the accepted preview: descending size order, bars, existing collapsible behavior, and concise timeout feedback.
No material question remains open. Routine choices use stable ties, a shared maximum, and one fill color.
## Scope
### In scope
- All existing storage resource rows, sorted by numeric measurements.
- Proportional bars, explicit partial state, accessible headers, and phone composition.
- Deadline warning normalization, retained partial samples, and preserved unrelated diagnostic examples.
- Localized copy, focused browser evidence, and operations guidance during implementation.
### Out of scope
- New categories, sorting controls, saved preferences, drilldown, or a Grafana dependency.
- Scan performance changes, longer deadlines, cleanup changes, or host-wide disk accounting.
- New APIs, persisted state, release flags, metrics, or changes to access restrictions.
- Commit, push, or PR creation.
## Technical approach
Task 01 changes `tempstore.measurementFromResult` and `summarize` to normalize joined warnings.
The frontend `systemTemporaryResource` turns the existing deadline reason into one localized explanation.
It also handles repeated deadline lines in older snapshots without hiding unrelated diagnostics.
The shared `filescan.Limiter` and scan cancellation lifecycle remain unchanged.
Task 02 adds numeric measurements to `StorageResource` and orders the canonical list from `storageResources`.
The local pure helper owns stable ordering and scale derivation.
`ResourceRow` renders the bar within `AccordionTrigger`.
Keep stable IDs, `Accordion type="multiple"`, detail actions, and the current snapshot preference.
The existing `storage-disk-capacity-card.tsx` provides the nearby track/token precedent.
Use decorative spans for these relative bars instead of its capacity progress semantics.
Use TDD for changed logic and focused browser tests for each visible outcome.
Install dependencies once from `apps/` before any pnpm command in a fresh worktree.
Reuse existing test fixtures and their isolated temporary roots.
### Companion packages
The completed [temporary-folder package](../storage-temporary-folders/plan.md) remains historical evidence.
Its manifest links this successor for the presentation changes.
The completed [analysis-progress package](../storage-analysis-progress/plan.md),
[database footprint package](../storage-database-footprint/plan.md), and
[progressive-loading package](../storage-progressive-loading/plan.md) define unchanged compatibility behavior.
Do not reopen their tasks or rewrite their result counts.
Run the affected existing component and Storage browser suites as specified in the work orders.
## ASCII UI preview
UI-00: Current desktop Storage analysis, based on the source and supplied screenshot.
Headers have labels and sizes, without bars. Categories use fixed order.
The expanded temporary-folder warning can contain many repeated deadline errors.
```text
Task workspaces 68.71 GB v
Database 7.09 GB v
Database backups 19.99 GB v
Quarantined resources 47.26 GB v
System temporary folders 51.08 GB ^
/tmp: 51.08 GB | Partial | 1,015 entries skipped
context deadline exceeded context deadline exceeded ...
```
UI-01: Proposed desktop, Settings > System > Storage, measured rows with one expanded.
Only the categories from the screenshot are shown here. Implementation includes every existing row.
```text
Storage analysis
Total counted: 242.71 GB
Bars compare category sizes. Categories can overlap.
Task workspaces [####################] 68.71 GB v
-----------------------------------------------------------
System temporary folders [Partial] [###############.....] 51.08 GB ^
Read-only. This footprint can overlap counted categories.
/tmp: 51.08 GB | Partial | 1,015 entries skipped
Scan timed out. Showing partial usage.
<up to ten distinct non-timeout diagnostic examples>
-----------------------------------------------------------
Quarantined resources [##############......] 47.26 GB v
-----------------------------------------------------------
Database backups [######..............] 19.99 GB v
-----------------------------------------------------------
Database [##..................] 7.09 GB v
```
The Partial label belongs to the header beside the size and can wrap beneath it.
The total is retained from the screenshot. It is not the sum of these example rows.
UI-02: Proposed phone, same entry and expanded state.
```text
Storage analysis
Total counted: 242.71 GB
Bars compare category sizes.
Categories can overlap.
Task workspaces 68.71 GB v
[##############################]
-----------------------------------
System temporary folders [Partial] ^
51.08 GB
[######################........]
Read-only. This footprint can
overlap counted categories.
/tmp: 51.08 GB
Partial | 1,015 entries skipped
Scan timed out.
Showing partial usage.
-----------------------------------
Quarantined resources v
47.26 GB
[#####################.........]
```
UI-03: First-scan and unavailable states, shared semantic order.
Phone bars occupy the line beneath each measured header.
```text
Database backups [##########..........] 10.00 GB v
Database [....................] 0.00 GB v
Task workspaces Scanning v
System temporary folders Unavailable v
```
The first track is illustrative. A larger measured row can precede this excerpt.
Unmeasured rows have no measured track. All-zero snapshots show only empty measured tracks.
Existing failed-refresh feedback stays visible above the retained snapshot.
Required structure: whole-row activation, descending measured order, stable row identity,
inline expanded details, common bar scale, and a two-line phone header.
There is one page scroll owner and no fixed region or new overlay.
Phone triggers have at least 44-pixel hit targets. Labels and paths wrap.
Spacing, example sizes, and ASCII fill density are illustrative, not pixel specifications.
UI-01 and UI-02 map to AC-003.10 and AC-005.1–.7.
UI-03 maps to AC-005.3 and .8.
Here, short AC references use the prefix `AC-SYSTEM-PAGE-STORAGE-MAINTENANCE`.
## Tests
Proposed test names are implementation targets, not claims of existing coverage.
| Criteria | Test file and proposed case |
| --- | --- |
| 003.10 | `tempstore/provider_test.go`: `TestTemporaryDeadlineWarningsAreBounded`, mixed error leaves, distinct roots, retained sample/counts |
| 003.6, .10 | Existing `TestAnalyzeTemporaryDeadlineReturnsPartialSample` and cancellation tests |
| 003.10 | `storage-overview-card.test.tsx`: `shows one localized timeout and preserves unrelated diagnostics`, including older joined warnings |
| 005.1, .2, .3 | New `storage-overview-resources.test.ts`: `maps every resource measurement`, `sorts numeric sizes with stable ties`, `handles zero and missing sizes` |
| 005.2, .3 | Same new test file: `scales against the largest measured footprint`, including all-zero and partial data |
| 005.4, .8 | `storage-overview-card.test.tsx`: `preserves expanded and focused rows after refresh reordering`, first-scan and stale-snapshot cases |
| 005.5 | Existing `storage-totals.test.ts`: informational and subset exclusions remain unchanged |
| 005.6, .7 | Component assertions for label, size, partial status, decorative bars, and localized descriptions |
Frontend test paths are relative to `apps/web/components/settings/system/storage/`.
Backend test paths are relative to `apps/backend/internal/system/storage/`.
## E2E tests
| Work order | Files and projects | Required evidence |
| --- | --- | --- |
| 01 | Existing `tests/system/storage-temporary-folders.spec.ts`, chromium; `mobile-storage-temporary-folders.spec.ts`, mobile-chrome | Open partial row, one timeout explanation, retained size/counts and unrelated warning, long-path wrapping, no horizontal overflow |
| 02 | New `tests/system/storage-analysis-bars.spec.ts`, chromium; `mobile-storage-analysis-bars.spec.ts`, mobile-chrome | Descending order, proportional fills, zero/unknown states, partial header, independent expansion, reorder/refresh preservation, no cleanup request |
| 02 | Existing Storage maintenance and temporary-folder suites in both projects | Existing actions, snapshots, and disclosures remain usable |
New files live in `apps/web/e2e/tests/system/`.
Fixtures use `test-base` and controlled overview responses through `helpers/storage-maintenance.ts`.
Never measure the developer's host temporary directory for browser assertions.
Use the configured Pixel 5 project. Add breakpoint geometry cases at 767 and 768 pixels.
Assert actual trigger height, bar placement, header containment, and no document horizontal overflow.
Capture and inspect desktop and phone screenshots through `prCapture`.
Exact commands are in each work order. The managed runner builds current assets and cleans its own instance.
Run desktop and mobile commands separately. Do not overlap suites or override worker limits.
## Work orders
- [x] [Task 01: Concise temporary-folder timeout feedback](task-01-timeout-feedback.md)
- [x] [Task 02: Sorted storage bars](task-02-sorted-storage-bars.md)
## Verification results
Implementation verification on 2026-09-22:
- `go test ./internal/system/storage/tempstore ./internal/system/storage/filescan`: passed.
- Focused Storage component suite: passed, 4 files and 38 tests.
- `pnpm exec tsc --noEmit --pretty false`: passed.
- Storage and new browser-file ESLint: passed with six existing test-only warnings and no errors.
- `pnpm --filter @kandev/web build:vite`: passed.
- `make -C apps/backend build`: passed.
- Managed desktop Storage browser command: passed, 13 tests.
- Managed mobile Storage browser command: passed, 11 tests.
- `node --test scripts/validate-public-docs.test.mjs` and `node scripts/validate-public-docs.mjs`: passed, 62 tests and 47 published pages.
- `python3 scripts/list-docs.py validate` and `python3 scripts/lint-spec-files.py --all`: passed, 299 decisions and 1109 specifications.
- `pnpm run i18n:ratchet`: passed; the scoped system namespace Traditional Chinese generation also passed.
- `git diff --check`: passed.
- Review follow-up: the serialized empty distinct Go cache now retains `unmanaged_size_bytes: 0`,
and the storage card preserves focused descendants, including row cleanup actions, during reorder.
- Focused desktop bars E2E after the review fix: passed, including held-refresh focus timing and
expanded-content assertions.
- Focused mobile bars E2E after the review fix: passed, 3 tests.
Design validation on 2026-09-22:
- `python3 scripts/list-docs.py validate`: passed, 299 decisions and 1109 specifications.
- `python3 scripts/lint-spec-files.test.py`: passed, 36 tests.
- `python3 scripts/lint-spec-files.py --all`: passed.
- `git diff --check -- docs/specs docs/plans`: passed.
- `git status --short -- docs/specs docs/plans`: confirmed the expected package and companion changes.
- Local document audit: all package links, requirement IDs, and work-order design paths resolve.
- Catalog output includes the new design under system-page.
The full `pnpm run i18n:check` command remains blocked by 32 pre-existing missing Japanese
catalog keys in the unrelated `executors` and `task` namespaces; the new storage keys are
complete and the new-code ratchet is clean. The global `pnpm run i18n:zh-hant` command has the
same pre-existing Traditional Chinese catalog gaps outside the `system` namespace.
No commit or publication occurred. Public operations guidance now documents relative bars and
temporary-folder timeout behavior. Delivery state belongs to this plan and its work orders.
## Risks
- Missing byte fields currently default to zero in some formatted rows. Sorting must not inherit that ambiguity.
- Mixed joined errors can contain a deadline and a real I/O error. Deadline filtering must preserve the latter.
- Bars compare overlapping and subset footprints. The total and capacity card must retain their separate meanings.
- First-scan completion can move rows. Stable keys must preserve focus and open details.
- Long localized labels can squeeze desktop bars or phone values. Rendered geometry checks cover both boundaries.
docs/plans/storage-analysis-presentation/task-01-timeout-feedback.md
+139
View File
@@ -0,0 +1,139 @@
---
id: "01-timeout-feedback"
title: "Concise temporary-folder timeout feedback"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-003
acceptance_criteria:
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.6
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.8
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.10
system_design:
- ../../specs/system-page/system-design/storage-analysis-presentation.md
---
# Task 01: Concise temporary-folder timeout feedback
## Summary
Replace repeated deadline messages with one localized explanation in the expanded temporary-folder row.
Preserve sampled bytes, partial state, skipped counts, and bounded non-deadline diagnostics.
## In scope
- TDD tests for repeated and mixed joined errors, multiple roots, counts, and cancellation.
- Normalize warning leaves at the tempstore projection boundary.
- Localize the existing deadline reason and normalize older warning payloads in the resource projection.
- Desktop and mobile browser assertions for bounded timeout feedback.
- Update the temporary-folder explanation in public operations guidance during implementation.
## Out of scope
Bars, sorting, new scanner workers, scan deadline changes, scan-performance work, cleanup, and new API fields.
## Acceptance
1. Deadline results retain sampled bytes and counts, with at most ten distinct non-deadline diagnostic examples.
2. Both new and older snapshots show one localized timeout explanation. Mixed joined errors retain unrelated diagnostics.
3. Desktop and phone users can inspect partial details without repeated deadline text or horizontal overflow.
## ASCII UI preview
UI-01 and UI-02 excerpt: expanded temporary-folder details at Settings > System > Storage.
See the [combined preview](plan.md#ascii-ui-preview). Bars belong to Task 02.
```text
Desktop:
System temporary folders 51.08 GB ^
Read-only. This footprint can overlap counted categories.
/tmp: 51.08 GB | Partial | 1,015 entries skipped
Scan timed out. Showing partial usage.
<bounded distinct diagnostic examples>
Phone:
System temporary folders ^
51.08 GB
Read-only. This footprint can
overlap counted categories.
/tmp: 51.08 GB
Partial | 1,015 entries skipped
Scan timed out.
Showing partial usage.
```
Maps to AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.6, .8, .10.
Existing inline expansion and one page scroll owner remain required.
Copy and paths wrap within the row. Example numbers and spacing are illustrative.
## Verification
Run from the repository root. Install workspace dependencies once before the first pnpm command.
Use deterministic injected scanner results instead of waiting for the production deadline.
Write the focused regression tests first and observe their failures before changing production logic.
```bash
(cd apps && pnpm install --frozen-lockfile)
(cd apps/backend && go test ./internal/system/storage/tempstore ./internal/system/storage/filescan)
(cd apps/web && pnpm test components/settings/system/storage/storage-overview-card.test.tsx components/settings/system/storage/storage-totals.test.ts)
(cd apps/web && pnpm exec eslint components/settings/system/storage/storage-overview-resources.ts components/settings/system/storage/storage-overview-card.test.tsx)
(cd apps/web && pnpm run typecheck)
(cd apps/web && pnpm run i18n:zh-hant)
(cd apps/web && pnpm run i18n:check)
(cd apps/web && pnpm run i18n:ratchet)
(cd apps/web && pnpm e2e:run --project chromium tests/system/storage-temporary-folders.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/system/mobile-storage-temporary-folders.spec.ts)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check
```
Before the final checks, add translations in en, pt-pt, zh-cn, and ja, then generate zh-hk and zh-tw.
Extend existing temporary-folder browser cases with a controlled deadline payload and one unrelated warning.
Assert one explanation, retained sampled size/counts, wrapped long paths, and no raw deadline repetitions.
Capture and inspect the desktop and phone detail region through `prCapture`.
## Files likely touched
- `apps/backend/internal/system/storage/tempstore/provider.go`
- `apps/backend/internal/system/storage/tempstore/provider_test.go`
- `apps/web/components/settings/system/storage/storage-overview-resources.ts`
- `apps/web/components/settings/system/storage/storage-overview-card.test.tsx`
- `apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw,ja}/system.json`
- `apps/web/e2e/helpers/storage-maintenance.ts`
- `apps/web/e2e/tests/system/storage-temporary-folders.spec.ts`
- `apps/web/e2e/tests/system/mobile-storage-temporary-folders.spec.ts`
- `docs/public/operations.md`
## Dependencies
None.
## Risks
- `errors.Is` on a joined error matches any deadline leaf. Do not discard the entire mixed error.
- Old cached warnings can contain many newline-separated deadline messages in one string.
- Existing cancellation and strict scanner consumers must retain their behavior.
## Parallelism
`sequential`. This order shares frontend and browser helper files with Task 02.
## Inputs
- [Requirements](../../specs/system-page/requirements/storage-maintenance.md), section 003.
- [Design](../../specs/system-page/system-design/storage-analysis-presentation.md), Deadline feedback.
- Existing `TestAnalyzeTemporaryDeadlineReturnsPartialSample` and temporary-folder component/browser cases.
- Scoped backend and web `AGENTS.md`, plus TDD, E2E, mobile-parity, and docs-maintainer skills.
## Results
- `go test ./internal/system/storage/tempstore ./internal/system/storage/filescan`: passed.
- Focused Storage component tests: passed, including the localized timeout and retained diagnostics case.
- Existing desktop and mobile temporary-folder browser cases: passed with one timeout explanation,
retained partial values and counts, unrelated diagnostics, and no horizontal overflow.
- Public operations guidance now documents partial timeout samples and their non-cleanup meaning.
docs/plans/storage-analysis-presentation/task-02-sorted-storage-bars.md
+172
View File
@@ -0,0 +1,172 @@
---
id: "02-sorted-storage-bars"
title: "Sorted storage bars"
status: done
wave: 2
depends_on:
- "01-timeout-feedback"
plan: "plan.md"
requirements:
- REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-005
acceptance_criteria:
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.1
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.2
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.3
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.4
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.5
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.6
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.7
- AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.8
system_design:
- ../../specs/system-page/system-design/storage-analysis-presentation.md
---
# Task 02: Sorted storage bars
## Summary
Add relative usage bars to all measured storage headers and sort by descending numeric size.
Preserve the existing Accordion, details, actions, refresh behavior, and phone access.
## In scope
- Numeric size projection for every existing category, including optional and subset rows.
- Stable sorting, common scale, zero and unknown states, and visible partial status.
- Desktop and phone header composition, localization, and accessibility.
- Unit, component, and browser coverage for order, scale, expansion, refresh, focus, and geometry.
- Public operations guidance for relative bars and unchanged counted totals.
## Out of scope
New categories, saved preferences, sort controls, host-capacity thresholds, chart libraries,
new scan behavior, nested resource sorting, cleanup actions, and backend schema changes.
## Acceptance
1. Eligible rows sort by descending bytes with stable ties and proportional fills. Missing measurements remain distinct from zero.
2. Existing expansion, focus, details, actions, and stale-snapshot behavior survive sorting and refresh.
3. Desktop and phone headers match the preview and pass localization, accessibility, geometry, and existing total checks.
## ASCII UI preview
UI-01: Desktop measured rows. UI-02: Phone measured rows.
See the [combined preview and state matrix](plan.md#ascii-ui-preview).
```text
Desktop:
Bars compare category sizes. Categories can overlap.
Task workspaces [####################] 68.71 GB v
System temporary folders [###############.....] 51.08 GB ^
Partial
/tmp: 51.08 GB | Partial | 1,015 entries skipped
Scan timed out. Showing partial usage.
Quarantined resources [##############......] 47.26 GB v
Phone:
Task workspaces 68.71 GB v
[##############################]
System temporary folders ^
51.08 GB | Partial
[######################........]
/tmp: 51.08 GB
Partial | 1,015 entries skipped
Scan timed out.
Showing partial usage.
```
UI-03: Unknown and zero states use the same row structure.
```text
Database [....................] 0.00 GB v
Task workspaces Scanning v
```
Maps to all AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005 criteria.
Required structure: shared scale, full-row activation, inline details, wrapped phone labels, and one page scroll owner.
Unknown rows have no measured bar. Partial remains visible in the header.
Keep 44-pixel phone/coarse-pointer targets and existing desktop density.
Example numbers, fill counts, and spacing are illustrative.
## Verification
Run from the repository root after Task 01. Workspace dependencies are already installed.
Write the focused unit/component and browser regressions before production changes.
```bash
(cd apps/web && pnpm test components/settings/system/storage/storage-overview-resources.test.ts components/settings/system/storage/storage-overview-card.test.tsx components/settings/system/storage/storage-totals.test.ts components/settings/system/storage/storage-disk-capacity-card.test.tsx)
(cd apps/web && pnpm exec eslint components/settings/system/storage)
(cd apps/web && pnpm run typecheck)
(cd apps/web && pnpm run i18n:zh-hant)
(cd apps/web && pnpm run i18n:check)
(cd apps/web && pnpm run i18n:ratchet)
(cd apps/web && pnpm e2e:run --project chromium tests/system/storage-analysis-bars.spec.ts tests/system/storage-maintenance.spec.ts tests/system/storage-temporary-folders.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/system/mobile-storage-analysis-bars.spec.ts tests/system/mobile-storage-maintenance.spec.ts tests/system/mobile-storage-temporary-folders.spec.ts)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check
```
Create `storage-overview-resources.test.ts` and the two bars E2E files named above.
Before the final checks, add all translations and generate the Traditional Chinese pair.
Use controlled snapshots with shuffled byte magnitudes, stable ties, zero, missing fields, and partial values.
Add a locale case where equal formatted sizes have different raw bytes.
Open two rows, focus one trigger, then replace the snapshot with changed magnitudes.
Assert both expanded identities survive and the focused resource remains focused.
Test first-scan source completion separately from stale-snapshot refresh.
Verify that sorting, expansion, and resizing issue no cleanup requests.
Check proportional fill geometry, text visibility, no new keyboard stops, and no horizontal overflow.
Verify the configured phone viewport and 767/768-pixel composition boundaries.
Capture and inspect desktop and phone screenshots through `prCapture`.
## Files likely touched
- `apps/web/components/settings/system/storage/storage-overview-resources.ts`
- `apps/web/components/settings/system/storage/storage-overview-resources.test.ts` (new)
- `apps/web/components/settings/system/storage/storage-overview-card.tsx`
- `apps/web/components/settings/system/storage/storage-overview-card.test.tsx`
- Optional local helper/component under the same directory, with its logic covered by the listed tests.
- `apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw,ja}/system.json`
- `apps/web/e2e/helpers/storage-maintenance.ts`
- `apps/web/e2e/tests/system/storage-analysis-bars.spec.ts` (new)
- `apps/web/e2e/tests/system/mobile-storage-analysis-bars.spec.ts` (new)
- `docs/public/operations.md`
- This plan, work orders, and the paired draft design for final status/results.
## Dependencies
Task 01, because both tasks change resource projection, localization, component tests, and browser fixtures.
This dependency orders integration and preserves the completed timeout behavior.
## Risks
- Parsing formatted values gives incorrect order across locales and rounded sizes.
- Array-index keys can transfer expansion to the wrong resource after sorting.
- Some existing rows represent subsets or overlaps. Never recalculate Total counted from bar rows.
- Desktop sizing assumptions can clip long translated labels on phones.
## Parallelism
`sequential`.
## Inputs
- [Requirements](../../specs/system-page/requirements/storage-maintenance.md), section 005.
- [Design](../../specs/system-page/system-design/storage-analysis-presentation.md), numeric mapping and presentation sections.
- Existing `StorageOverviewResources`, `ResourceRow`, `storageResources`, and capacity-card styling.
- Existing Storage maintenance browser fixtures and completed Task 01.
- Scoped web `AGENTS.md`, plus TDD, E2E, mobile-parity, and docs-maintainer skills.
## Results
- `storage-overview-resources.test.ts`: passed numeric mapping, stable sorting, common scale, zero,
missing, invalid, optional, and subset measurement cases.
- `storage-overview-card.test.tsx`: passed decorative bar, partial status, expansion, and focus
assertions; the full focused Storage component suite passed.
- Desktop and mobile bars browser suites: passed descending order, proportional fills, unknown and
zero states, refresh reordering, stable expansion and focus, touch target geometry, breakpoints,
and horizontal containment.
- Public operations guidance now explains relative bars and unchanged counted totals.
docs/plans/storage-temporary-folders/plan.md
+3
View File
@@ -13,6 +13,9 @@ legacy_specs: []
## Overview
The completed [storage analysis presentation package](../storage-analysis-presentation/plan.md)
extends row ordering, usage bars, and timeout feedback. This completed package retains its original evidence.
Deliver temporary-folder visibility first, then optional cleanup of registered artifacts, then integrated browser evidence.
Each slice preserves the distinction between measured storage and cleanup ownership.
All work stays sequential in the primary session.
docs/public/operations.md
+11 -1
View File
@@ -317,7 +317,17 @@ The Storage page also reports **System temporary folders** as a read-only footpr
service's effective temporary folder and, on Unix, `/tmp` when it resolves to a distinct folder.
Resolved roots, measured size, and partial or unavailable status are shown. This footprint is
informational and can overlap counted categories, so it is excluded from **Total counted**. It has
no cleanup action and does not claim ownership of any path.
no cleanup action and does not claim ownership of any path. The analysis rows use the measured byte
values to order categories from largest to smallest. A decorative bar compares each displayed
measurement with the largest displayed measurement; zero measurements have an empty bar, and
unknown or unavailable measurements have no bar. These bars compare footprints and do not change
**Total counted**, capacity thresholds, or cleanup behavior. Overlapping categories can therefore
appear in more than one row.
A temporary-folder scan that reaches its deadline keeps the sampled bytes, partial status, and
skipped-entry counts. The expanded row shows one timeout explanation and keeps a bounded set of
other diagnostic examples. A timeout does not authorize cleanup or indicate that the sampled size
is a final folder total.
The Host tab separately reports **Temporary Kandev files** created by services that need a short-lived
directory under the host temporary root. Each current file is registered in the Kandev database
docs/specs/system-page/requirements/storage-maintenance.md
+26 -1
View File
@@ -2,7 +2,7 @@
status: active
system: system-page
created: 2026-07-14
updated: 2026-09-12
updated: 2026-09-22
owners:
- cfl
---
@@ -90,6 +90,7 @@ The existing application size-unit convention remains unchanged.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.7:** Analysis shall not read file contents, follow nested symlinks, cross nested mounts, change ownership, or remove files.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.8:** Desktop and phone users shall inspect sizes, long paths, and limitations without horizontal page scrolling. Copy shall use the selected language.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.9:** Existing storage access restrictions shall apply. Analysis requests shall not accept arbitrary paths from clients.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.10:** When the temporary-folder scan reaches its deadline, the expanded row shall show one localized timeout explanation and retain sampled bytes and partial status. Repeated deadline messages shall not appear. Other diagnostics shall remain bounded to ten distinct examples, with existing skipped-entry counts preserved.
### REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-004: Scheduled cleanup of owned temporary artifacts
@@ -114,8 +115,32 @@ Shared-file deletion, legacy-directory adoption, arbitrary cleanup paths, config
new artifact producers, remote temporary folders, and changes to inherited agent temporary variables
are outside this extension. Whole-host disk reconciliation remains outside storage analysis.
### REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-005: Relative storage usage bars
**Intent:** Operators can identify the largest measured categories without opening each storage row.
#### Acceptance criteria
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.1:** Analysis rows shall sort by measured bytes, largest first. Equal sizes shall retain their existing category order. Unmeasured rows shall appear last in that order.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.2:** Each measured row shall show its size and a proportional bar in the collapsible header. Every bar shall use zero as its origin and the largest displayed measurement as its maximum.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.3:** Measured zero shall show an empty track and its size. Unknown, pending, failed, and not-applicable rows shall retain their status without a measured bar. Partial measurements shall use sampled bytes and retain visible partial status.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.4:** Rows shall retain independent expansion, keyboard activation, and existing detail actions. Sorting and refreshed measurements shall preserve expansion and focus for each remaining row.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.5:** Bars shall compare category footprints without changing Total counted or the separate filesystem-capacity indicator. Visible copy shall explain relative sizing and possible category overlap. Bar color shall not imply a cleanup recommendation or capacity threshold.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.6:** Desktop headers shall show label, bar, size, and chevron. Phone headers shall place the bar beneath the label and size. Labels and details shall wrap without horizontal page scrolling. Phone triggers shall have a touch target of at least 44 pixels.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.7:** Text shall communicate size, measurement status, and expansion without reliance on color. All new copy shall use the selected language. Bars shall not add keyboard stops or announce scan completion.
- **AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-005.8:** First-scan progress shall retain distinct unmeasured states as measured rows enter size order. A refresh shall keep the previous snapshot until its atomic replacement. Existing refresh and failure behavior shall remain available.
#### Exclusions
New categories, sorting controls, saved order preferences, per-file drilldown, cleanup policy changes,
scan deadline changes, and host-wide disk attribution are outside this extension.
## System design
The implemented usage bars and timeout feedback are defined in
[Storage analysis presentation](../system-design/storage-analysis-presentation.md).
The [plan package](../../../plans/storage-analysis-presentation/plan.md) records implementation and verification evidence.
The implemented temporary-storage extension is defined in
[Temporary storage visibility and cleanup](../system-design/storage-temporary-folders.md).
Its [implementation package](../../../plans/storage-temporary-folders/plan.md) contains completed work orders.
docs/specs/system-page/system-design/storage-analysis-presentation.md
+173
View File
@@ -0,0 +1,173 @@
---
status: current
system: system-page
requirements:
- REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-003
- REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-005
created: 2026-09-22
owners:
- kandev
---
# Storage analysis presentation
## Purpose and boundaries
System-page owns storage measurements and their operator-facing presentation.
This design extends the existing Storage accordion with relative bars and concise deadline feedback.
It preserves the [temporary-storage reader](storage-temporary-folders.md), cleanup ownership, and classified total.
The user accepted descending bars, unchanged collapsible behavior, a phone layout, and concise timeout feedback.
The implementation is recorded in the [plan package](../../../plans/storage-analysis-presentation/plan.md).
No new persistence, endpoint, release flag, scan limit, or cleanup action is required.
## Requirement mapping
| Requirement or criterion | Design section |
| --- | --- |
| AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.10 | Deadline feedback |
| REQ-SYSTEM-PAGE-STORAGE-MAINTENANCE-005 | Resource measurements, Ordering and scale, Accordion presentation |
| AC-SYSTEM-PAGE-STORAGE-MAINTENANCE-003.3, .6, .8 | Compatibility, Deadline feedback, Phone composition |
## Current source evidence
Paths below are relative to the repository root.
- `apps/backend/internal/system/storage/filescan/measure.go` joins partition errors in `Limiter.MeasureWithOptions`.
- `apps/backend/internal/system/storage/tempstore/provider.go` walks joined error leaves in
`measurementFromResult`, removes deadline leaves, and retains distinct non-deadline diagnostics.
- The warning count is bounded at the projection boundary, including warnings carried by joined errors.
- `storage-overview-resources.ts` normalizes warning strings for the visible row and projects numeric
measurements for sorting and scale derivation.
- `StorageResource` carries optional numeric size, bar scale, and partial-state fields alongside
localized display values.
- `StorageOverviewResources` renders `Accordion type="multiple"`, with stable resource IDs as keys and item values.
Frontend filenames in this design are under `apps/web/components/settings/system/storage/`, unless another path is given.
## Resource measurements
Extend the local `StorageResource` view model with optional `sizeBytes` and a partial-status field.
Read numeric bytes from the current summary. Never parse `value`, which contains localized text.
Do not change the public `StorageOverviewResponse` shape.
| Row | Numeric source |
| --- | --- |
| Task workspaces | `workspaces.total_bytes` |
| Database / Database backups | respective `size_bytes` for measured status |
| Quarantine | `quarantine.size_bytes` unless unavailable |
| System temporary folders | `system_temporary.size_bytes` for measured or partial status |
| Managed Go cache | `go_cache.size_bytes` unless unavailable |
| Distinct user Go cache | `go_cache.unmanaged_size_bytes`, only for the existing distinct-path row |
| Registered temporary artifacts | `temporary_artifacts.total_bytes` unless unavailable |
| Kandev containers | `docker.managed_container_bytes` when Docker is available |
| Docker image layers | `docker.image_layer_bytes` when Docker is available |
| Docker build cache | `docker.build_cache_bytes` when Docker is available |
| Unused Docker images | `docker.unused_image_bytes` when Docker is available |
Only finite, nonnegative numbers are eligible. Missing or invalid fields have no numeric bar.
Explicit zero is a measurement. Do not convert absent values to zero for sorting or display.
Status gates take precedence over stale numeric fields in unavailable or not-applicable responses.
Keep existing detail text, source progress, ownership warnings, and action handlers.
Expose the existing system-temporary partial status in its header beside the row title.
## Ordering and scale
Build the existing canonical category list, then sort a copy by descending `sizeBytes`.
Use canonical category position for equal measurements and unmeasured rows.
All numeric measurements, including zero and partial samples, precede unmeasured rows.
Locale changes must not change ties. Keep all existing categories, including subset measurements.
The maximum is the largest eligible measurement in the displayed snapshot.
Each fill is `100 * sizeBytes / maximum`, clamped to 0–100.
For an all-zero snapshot, every measured track is empty. Never divide by zero.
Do not impose a minimum fill that overstates small measurements.
Keep the current `summary ?? analysis.partial_summary` snapshot preference.
First-scan source completion updates order and scale from available measurements.
During refresh, the displayed snapshot continues to own both until atomic replacement.
Keep resource IDs stable so ordering does not reset expansion, focus, or existing action state.
No saved sort state or additional scan requests are required.
The maximum includes informational and subset rows because their full footprints are being compared.
It is not Total counted or disk capacity. Existing overlap rules in `storage-totals.ts` remain unchanged.
## Accordion presentation
Keep the existing Accordion and full-row trigger, including its chevron and keyboard behavior.
Use a flexible desktop header with label, rounded track, size, then chevron.
Use existing theme tokens for the muted track and one consistent fill.
Use amber status text or a badge beside the row title for partial measurements, without encoding size thresholds.
Keep existing action buttons inside expanded content.
Render bars as decorative spans with `aria-hidden="true"`.
The trigger already exposes the label, formatted size, partial status, and expansion.
A relative footprint is not scan progress. Do not give it progress-bar semantics.
Bars introduce no tooltip, keyboard stop, animation requirement, or nested interactive control.
Add visible localized explanatory text near the rows:
"Bars compare category sizes. Categories can overlap."
Keep the existing classified-total scope explanation.
Long labels wrap. Numeric values and chevrons remain readable.
## Phone composition
Entry: Settings > System > Storage. Primary row action: tap to expand or collapse.
The nearest shipped exemplar is the Storage accordion in `mobile-storage-maintenance.spec.ts`.
Its inline detail and whole-row activation fit short reference content.
The curated mobile guide contributes one focal flow, visible actions, and a single scroll owner.
Below the existing 768-pixel phone boundary, place the bar beneath the label and value.
A long label can occupy its own line. Keep the chevron at the trailing edge.
Use one shared resource model and Accordion state across viewport changes.
The existing page owns scrolling and safe-area behavior. Do not add a fixed footer or nested scroller.
Keep phone/coarse-pointer trigger hit targets at least 44 pixels.
Preserve desktop density and existing action sizing.
Verify the configured Pixel 5 viewport, 767 pixels, and 768 pixels.
Check actual bar position, target bounds, wrapped paths, and page containment.
The plan owns the exact [ASCII previews](../../../plans/storage-analysis-presentation/plan.md#ascii-ui-preview).
## Deadline feedback
Retain the current 60-second source deadline, sampled bytes, partial status, and `reason: deadline`.
A deadline explains an incomplete measurement. It does not imply failed cleanup or corrupt storage.
Normalize warning examples at the `tempstore` projection boundary.
Walk joined error leaves before converting them into strings.
Discard leaves classified as `context.DeadlineExceeded`, while retaining distinct non-deadline diagnostics.
Do not discard a mixed joined error merely because `errors.Is` finds a deadline somewhere inside it.
Merge remaining examples with `result.Warnings`, deduplicate them, and apply the existing ten-example limit.
Apply the same deduplication when `summarize` combines root warnings.
Retain skipped-entry counts exactly. Cancelled partitions do not invent skipped-entry counts.
Keep parent cancellation behavior and shared strict scanner callers unchanged.
In `systemTemporaryResource`, derive one localized explanation from the summary or root `reason: deadline`:
"Scan timed out. Showing partial usage."
Show it once in the expanded category, alongside existing root sizes, partial status, and skipped counts.
Other bounded diagnostics remain visible.
Handle cached or older payloads at this same frontend boundary.
Split legacy warning strings on line breaks, discard exact trimmed deadline-only lines, and deduplicate remaining examples.
Use structured reasons first. Legacy exact deadline-only lines can also identify this known timeout.
Do not match arbitrary path substrings or hide unrelated warnings.
Cap the rendered examples at ten, independently of the timeout explanation.
No cache flush, migration, automatic retry, or new diagnostic overlay is required.
## Compatibility and verification
The [temporary-storage ownership decision](../../../decisions/2026-09-11-temporary-storage-visibility-policy.md)
remains authoritative. Analysis grants no cleanup authority.
Storage access restrictions, safe traversal, events, and API authorization remain unchanged.
Total counted excludes system temporary folders and avoids double-counting existing subsets.
All new copy uses `t()` in the `system` namespace.
Update English, pt-pt, zh-cn, zh-hk, zh-tw, and ja.
Generate the Traditional Chinese pair with `pnpm run i18n:zh-hant`.
Use deterministic joined errors and injected scanner results for timeout tests.
Do not wait 60 seconds or scan host temporary folders.
Use frontend unit tests for source mapping, sorting, invalid values, ratios, and old payloads.
Use component and browser tests for expansion, refresh, focus, localization, and mobile geometry.
The plan records exact commands and implementation results.
Public operations documentation now explains relative bars and temporary-folder timeout behavior.
docs/specs/system-page/system-design/storage-temporary-folders.md
+6 -1
View File
@@ -143,6 +143,10 @@ Permanent deletion retains its existing reporting and retention deadline.
## Presentation
The current [storage analysis presentation design](storage-analysis-presentation.md) extends row ordering
and timeout feedback. Its measured size order supersedes the adjacency described below.
The existing reader, ownership, totals, and cleanup contracts remain authoritative.
Add a System temporary folders disclosure beside Kandev temporary artifacts in the analysis section.
Show full folder size and the visible note: `Informational. Can overlap counted categories.`
Expanded content shows resolved roots, partial status, and measurement limitations.
@@ -161,7 +165,8 @@ Keep one page scroll owner. Paths wrap within the resource detail.
Keep required help visible inline. No tooltip or overlay is needed to understand cleanup scope.
Phone controls have at least 44-pixel hit targets. Fine-pointer buttons retain 28-pixel density.
No fixed toolbar or new navigation route is required.
All new copy uses `system` translations in all five supported language catalogs.
All new copy uses `system` translations in the `en`, `pt-pt`, `zh-cn`, `zh-hk`,
`zh-tw`, and `ja` language catalogs.
## Verification and delivery