Carlos Florêncio
13 KiB
created, status, requirements, system_design, legacy_specs
| created | status | requirements | system_design | legacy_specs | |||
|---|---|---|---|---|---|---|---|
| 2026-09-22 | implemented |
|
|
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: 003.10 and requirement 005.
- System design.
- Existing temporary-storage decision.
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 remains historical evidence. Its manifest links this successor for the presentation changes. The completed analysis-progress package, database footprint package, and progressive-loading package 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.
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.
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.
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.
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
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.mjsandnode scripts/validate-public-docs.mjs: passed, 62 tests and 47 published pages.python3 scripts/list-docs.py validateandpython3 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.