182 lines
9.7 KiB
Markdown
182 lines
9.7 KiB
Markdown
---
|
|
spec: docs/specs/system-page/requirements/storage-maintenance.md
|
|
created: 2026-08-08
|
|
status: complete
|
|
---
|
|
|
|
# Implementation Plan: Registered Kandev temporary-artifact cleanup
|
|
|
|
## Overview
|
|
|
|
Add a manual-only `temporary_artifacts` resource to the existing Storage page. The backend first
|
|
gets a durable registry and marker contract for exact Kandev service-created temporary roots, then
|
|
adds analysis/quarantine/API composition, followed by the responsive resource action and desktop /
|
|
mobile coverage. The implementation must preserve the inherited shared-temp boundary: anonymous
|
|
`/tmp` folders, caches, preview/CI roots, and other-installation data are never swept.
|
|
|
|
The architectural boundary is recorded in
|
|
[ADR-2026-08-08-owned-temp-artifact-cleanup](../../decisions/2026-08-08-owned-temp-artifact-cleanup.md),
|
|
which supplements [ADR 0045](../../decisions/0045-install-wide-storage-maintenance.md).
|
|
|
|
---
|
|
|
|
## Backend
|
|
|
|
### Ownership registry and producer lifecycle
|
|
|
|
- Add a `storage_temp_artifacts` table and replay-safe migration in
|
|
`apps/backend/internal/system/storage/store_migrations.go`, with exact path, allowlisted kind,
|
|
artifact ID, marker token, lifecycle state, owner PID/lease timestamps, and metadata.
|
|
- Add `apps/backend/internal/system/storage/tempartifacts/` with registry operations that create
|
|
top-level directories below the effective service temp root, write an owner-only marker atomically,
|
|
persist the record, heartbeat active leases, close normal lifecycles, and reconcile records after
|
|
restart. All path checks use `Lstat`/canonical containment and fail closed on symlinks or
|
|
uncertainty.
|
|
- Migrate backend-owned long-lived roots in `apps/backend/internal/improvekandev/bundle.go` and
|
|
`apps/backend/internal/agent/hostutility/manager.go` to the registry. Remove the independent
|
|
name/age sweep from `apps/backend/internal/backendapp/helpers.go`; unregistered legacy roots stay
|
|
host-policy data.
|
|
|
|
### Storage provider and API composition
|
|
|
|
- Implement analysis and explicit cleanup in `tempartifacts/provider.go`: report total, active,
|
|
stale-candidate, skipped, and unavailable bytes/counts; only closed or abandoned records older
|
|
than 24 hours qualify; same-filesystem rename moves a qualifying root to the existing quarantine.
|
|
- Extend storage summary/capability types and `storage_quarantine_entries.resource_type` for
|
|
`temporary_artifact`. Reuse quarantine retention, restore, and permanent deletion; do not add a
|
|
`storage_maintenance` setting in this release.
|
|
- Reuse `ExplicitCleanupProvider` so `temporary_artifacts` is no-op for scheduled and unscoped
|
|
full runs but performs cleanup for `resources: ["temporary_artifacts"]`. Extend provider
|
|
composition in `apps/backend/internal/backendapp/storage_maintenance.go` and keep overview totals
|
|
non-overlapping.
|
|
- Accept the stable resource name through the existing `POST /api/v1/system/storage/run` contract;
|
|
return provider counts/bytes and skipped warnings through the existing run result and preserve
|
|
the current activity gate and busy/force behavior.
|
|
|
|
---
|
|
|
|
## Frontend
|
|
|
|
### Storage analysis and action
|
|
|
|
- Extend `apps/web/lib/types/system.ts` with the temporary-artifact summary, capability, quarantine
|
|
resource type, and provider result shapes. No new policy field is added.
|
|
- Update `apps/web/components/settings/system/storage/storage-totals.ts` so measured temporary
|
|
artifact bytes participate once in the non-overlapping total, with a partial result when that
|
|
provider is unavailable.
|
|
- Add a localized **Kandev temporary artifacts** resource row to
|
|
`apps/web/components/settings/system/storage/storage-overview-card.tsx`. Show measured bytes,
|
|
stale eligible bytes/count, active protection, skipped warnings, and an explicit
|
|
**Clean stale artifacts** action only when cleanup is available.
|
|
- Thread `runNow(["temporary_artifacts"])` through the existing Storage controller and add a normal
|
|
reversible confirmation in `storage-confirmation-dialogs.tsx`; do not introduce a second page or
|
|
a scheduled toggle. Keep busy feedback and `Run anyway` on the existing gate.
|
|
- Add the new copy to `en`, `pseudo`, `pt-pt`, and `zh-cn` `system.json` catalogs. All paths remain
|
|
i18n-guarded and filesystem values are interpolated rather than translated.
|
|
|
|
### Mobile contract
|
|
|
|
- Keep the existing one-column Storage accordion and action composition. The temporary-artifact row
|
|
must wrap long paths/warnings, retain a 44px-or-larger action target, and remain usable with no
|
|
horizontal document overflow at the mobile project viewport.
|
|
|
|
---
|
|
|
|
## Tests
|
|
|
|
- **Registry persistence and marker safety:** create/close/heartbeat/reconcile registered artifacts,
|
|
reject unregistered prefixes, missing or mismatched markers, symlink replacement, path escape, and
|
|
cross-install/legacy records. **Files:**
|
|
`apps/backend/internal/system/storage/tempartifacts/*_test.go`,
|
|
`apps/backend/internal/system/storage/store_test.go`,
|
|
`apps/backend/internal/improvekandev/bundle_test.go`, and host-utility lifecycle tests.
|
|
**How:** table-driven filesystem tests under `t.TempDir()` plus SQLite migration/restart tests.
|
|
- **Provider behavior:** analysis is read-only, active/recent roots are protected, stale roots move
|
|
atomically to quarantine, cross-device/error/symlink cases remain untouched, and unscoped/scheduled
|
|
runs do not invoke destructive temp cleanup. **Files:**
|
|
`apps/backend/internal/system/storage/tempartifacts/provider_test.go`,
|
|
`apps/backend/internal/system/storage/operations_test.go`, and
|
|
`apps/backend/internal/system/storage/runner_test.go`.
|
|
**How:** fake clocks, fake leases, fake rename/filesystem adapters, and provider result assertions.
|
|
- **API and composition:** the overview exposes the new summary, `temporary_artifacts` is accepted
|
|
only as a valid explicit resource, quarantine rows round-trip the new resource type, and handler
|
|
errors preserve `400`/`409` semantics. **Files:**
|
|
`apps/backend/internal/system/storage/handler_test.go`, `storage_routes_test.go`, and
|
|
`apps/backend/internal/backendapp/storage_test.go`.
|
|
**How:** handler-to-service-to-store tests with real SQLite and a fake provider, plus composition
|
|
wiring coverage.
|
|
- **Frontend rendering/action:** the row shows active versus stale state, the confirmation sends the
|
|
exact resource selection, success/error/busy feedback remains localized, and existing Go-cache /
|
|
global actions remain unchanged. **Files:**
|
|
`apps/web/components/settings/system/storage/storage-overview-card.test.tsx`,
|
|
`storage-confirmation-dialogs.test.tsx`,
|
|
`storage-totals.test.ts`,
|
|
`apps/web/hooks/domains/system/use-storage-maintenance.test.tsx`, and
|
|
`apps/web/lib/api/domains/system-api.test.ts`.
|
|
**How:** Vitest and Testing Library interaction tests with mocked overview/run responses.
|
|
|
|
---
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenario:** a current-install registered stale artifact and an unregistered `kandev-*` folder
|
|
are present, **WHEN** Storage analysis runs, **THEN** only the registered artifact appears in the
|
|
temporary-artifact row and the unregistered folder is not counted or changed. **File:**
|
|
`apps/web/e2e/tests/system/storage-maintenance.spec.ts` using the existing Storage API route
|
|
fixture pattern plus an explicit-run assertion.
|
|
- **Scenario:** the user selects **Clean stale artifacts**, **WHEN** confirmation completes,
|
|
**THEN** the request contains `{ resources: ["temporary_artifacts"] }`, the cleanup job completes,
|
|
and the result is visible in Quarantine while a global **Run now** leaves the artifact untouched.
|
|
**File:** `apps/web/e2e/tests/system/storage-maintenance.spec.ts`.
|
|
- **Scenario:** the same row and confirmation are opened from the mobile settings sheet, **WHEN**
|
|
the user taps the action, **THEN** the action is reachable at a 44px target and the document has no
|
|
horizontal overflow. **File:** `apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts`.
|
|
|
|
Focused UI commands use the managed production-build runner:
|
|
|
|
```bash
|
|
cd apps/web && pnpm e2e:run tests/system/storage-maintenance.spec.ts
|
|
cd apps/web && pnpm e2e:run tests/system/mobile-storage-maintenance.spec.ts -- --project=mobile-chrome
|
|
```
|
|
|
|
---
|
|
|
|
## Verification Results
|
|
|
|
- Backend storage, Improve Kandev, host-utility, and backend-app tests passed:
|
|
`go test ./internal/system/storage/... ./internal/improvekandev/... ./internal/agent/hostutility/... ./internal/backendapp/... -count=1`.
|
|
- Focused frontend tests passed: 71 tests across six files; web typecheck and lint passed.
|
|
- `pnpm run i18n:check` and `pnpm run i18n:ratchet` passed. The check reported only the
|
|
repository's existing 209 advisory pt-pt/zh-cn parity issues and one existing orphan.
|
|
- Desktop Storage Playwright: 7 passed, including the registered-artifact row, scoped cleanup,
|
|
quarantine/job feedback, cache isolation, busy override, progressive loading, and settings
|
|
persistence scenarios.
|
|
- Mobile Storage Playwright: 5 passed, including the scoped action, touch target, and document
|
|
overflow assertions.
|
|
- Public documentation validation passed: 58 tests and 41 published pages. `git diff --check`
|
|
passed.
|
|
|
|
---
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Wave 1 (sequential backend foundation):
|
|
|
|
- [x] [Task 01 — Temp ownership registry and producer lifecycle](task-01-temp-ownership-registry.md)
|
|
|
|
Wave 2 (backend provider/API after Task 01):
|
|
|
|
- [x] [Task 02 — Temporary-artifact storage provider and API](task-02-temp-artifact-provider-api.md)
|
|
|
|
Wave 3 (frontend after Task 02; shared frontend files make this sequential):
|
|
|
|
- [x] [Task 03 — Storage temporary-artifact action](task-03-storage-temp-artifact-ui.md)
|
|
|
|
Wave 4 (desktop/mobile E2E after Task 03):
|
|
|
|
- [x] [Task 04 — Temporary-artifact Storage E2E coverage](task-04-storage-temp-artifact-e2e.md)
|
|
|
|
Wave 5 (docs after behavior is implemented):
|
|
|
|
- [x] [Task 05 — Temporary-artifact operations documentation](task-05-storage-temp-artifact-docs.md)
|