Files
kandev/docs/plans/storage-temp-artifacts/plan.md
T
2026-08-24 11:09:03 +00:00

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)