curo/kite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: curo/kite:v0.2
Branches Tags
curo/kite:main
curo/kite:v0.2
...
compare: curo/kite:90e1b525f1b69d06bf77bf00933c47b5488a61f4
Branches Tags
curo/kite:main
curo/kite:v0.2
172 Commits
v0.2 ... 90e1b525f1
Author SHA1 Message Date
curo1305andClaude Sonnet 4.6 90e1b525f1 docs(14-09): Phase 14 closeout — docs, version bump v0.3.0→v0.4.0, security evidence 
- CLAUDE.md/AGENTS.md: update current-state line to v0.4.0 Phase 14 complete;
  add Phase 14 shared module map entries (cloud_cache, cloud_analysis,
  cloud_analysis_processing, cloud_analysis_tasks, analysis router, cache API);
  add Phase 14 non-negotiable rules (hydrate_and_cache_bytes single entry point,
  IDs-only broker payload, object_key/credentials_enc excluded at schema level)
- README.md: bump to v0.4.0; add Selective cloud analysis and Cloud byte cache
  features; add Analysis API table (Phase 14 endpoints)
- SECURITY.md: add Phase 14 threat register (T-14-01..T-14-15) with evidence,
  security gate results, and accepted risks
- backend/main.py: bump FastAPI version to 0.4.0
- frontend/package.json: bump version to 0.4.0
- ROADMAP.md: mark Phase 14 complete (9/9 plans), plan 14-09 checked off
- 14-VALIDATION.md: gate evidence, requirement coverage, acceptance criteria check
- 14-SECURITY.md: security evidence summary and gate checklist

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-23 20:05:49 +02:00
curo1305 2d697a6036 docs(14-08): complete settings integration plan 2026-06-23 19:55:32 +02:00
curo1305 ba15811f91 feat(14-08): add Analysis Settings section to SettingsCloudTab 
- Add cache limit number input with tier cap validation and usage display
- Add segmented control for simplified vs detailed analysis progress (D-06)
- Add segmented control for pause-batch vs continue-item failure behavior (D-11)
- Load cache settings on mount via loadCacheSettings; surface API errors
- Keep existing connection health/reconnect/disconnect UX intact
- All 471 frontend tests pass; no regressions
 2026-06-23 19:52:23 +02:00
curo1305 6fc30ac755 feat(14-08): add cache settings API/store wiring for Settings integration 
- Fix getCacheSettings/updateCacheSettings URLs to use /api/cloud/analysis/cache
  and /api/cloud/analysis/cache/settings (Rule 1: wrong URLs per Plan 14-03 backend)
- Add loadCacheSettings action: hydrates tierCapBytes, cacheUsage, cacheLimit,
  detailedAnalysisProgress, failureBehavior from server without clearing on error
- Add tierCapBytes, cacheUsage, cacheSettingsLoading, cacheSettingsError state
- updateCacheSettings merges full CacheStatusOut response into local state
 2026-06-23 19:50:35 +02:00
curo1305 22e33f1255 docs(14-07): complete frontend analysis UX plan 2026-06-23 19:46:13 +02:00
curo1305 04e6ea2ba2 feat(14-07): extend StorageBrowser and CloudFolderView with analysis UX (Task 2) 
StorageBrowser:
- Add analyze-file button per cloud file row (D-01); placed inside name cell
  to avoid interfering with capability-gated file-row-actions (Rule 1 compliance)
- Add file-select checkboxes for multi-select analysis (cloud mode only)
- Add analyze-selection toolbar button (D-01, ANALYZE-02)
- Add analyze-folder toolbar button when breadcrumb is non-empty (D-01)
- Add analyze-connection toolbar button when connectionRoot is set (D-01, ANALYZE-03)
- Add analysisEstimate prop + analysis-estimate-modal (D-03) with estimate-start button
- Add analysisQueue prop + analysis-aggregate-progress with simplified/detailed labels (D-05/D-06)
- Add expandable per-item list via analysis-queue-expand toggle (D-05)
- Add per-item cancel/retry/skip controls in expanded list (D-09, ANALYZE-05)
- Add Cancel all batch button (D-09, ANALYZE-05)
- Emit: analyze-file, analyze-selection, analyze-folder, analyze-connection,
  analysis-confirmed, analysis-cancelled, analysis-item-cancel/retry/skip, analysis-cancel-all

CloudFolderView:
- Pass analysis props to StorageBrowser from cloudStore
- Add analysis estimate, pending request state
- Handle all analysis emits: onAnalyzeFile, onAnalyzeSelection, onAnalyzeFolder,
  onAnalyzeConnection, onAnalysisConfirmed, onAnalysisItemCancel/Retry/Skip, onAnalysisCancelAll
- Routes all API calls through cloudStore (requestEstimate, enqueueAnalysis, etc.)
 2026-06-23 19:42:53 +02:00
curo1305 1291040f9b feat(14-07): add analysis API helpers and store state/actions (Task 1) 
- Add estimateAnalysis, enqueueAnalysis, getAnalysisJobStatus, listAnalysisJobs,
  cancelAnalysisJob, cancelAnalysisItem, skipAnalysisItem, retryAnalysisItem,
  getCacheSettings, updateCacheSettings to api/cloud.js
- Extend cloudConnections store with analysis state: activeAnalysisJob, analysisQueue
  (computed), failureBehavior, detailedAnalysisProgress, cacheLimit
- Add store actions: requestEstimate, enqueueAnalysis, fetchJobStatus, cancelJob,
  retryItem, skipItem, cancelItem, setFailureBehavior, setDetailedAnalysisProgress,
  updateCacheSettings
- Add translateAnalysisStatus (D-06: single translation source for components)
- Status labels: simplified (waiting/working/done/skipped/failed) and detailed modes
- Credentials never stored in queue state (T-14-02)
 2026-06-23 19:35:33 +02:00
curo1305 a2b7928ba4 docs(14-06): complete byte cache for open/preview/download plan 2026-06-23 16:33:01 +02:00
curo1305 b84b912acf test(14-06): add cache transparency assertion to frontend open/preview tests 
- Add cache_backed_response_has_no_object_key describe block to CloudFolderOpenPreview.test.js
- Verifies openCloudFile response processed by CloudFolderView never exposes object_key, MinIO paths, or credentials_enc in rendered HTML or API call arguments (T-14-02)
- All 9 tests pass (8 pre-existing + 1 new)
 2026-06-23 16:29:11 +02:00
curo1305 dfc335022f feat(14-06): route preview/download bytes through durable byte cache 
- Add hydrate_and_cache_bytes to services/cloud_cache.py (Plan 06 cache lifecycle)
  - Cache-hit path: pin existing entry, read from MinIO, release pin in finally
  - Cache-miss path: fetch from provider, store in MinIO, create/reactivate entry, pin during response, release pin in finally
  - CacheQuotaExceeded and MinIO failures are non-fatal (bytes returned from provider path)
  - evict_lru_entries run after pin release to stay within user cache limit
- Update preview_cloud_file and download_cloud_file in operations.py to call hydrate_and_cache_bytes
  - Version key computed from CloudItem metadata (no provider call required for key resolution)
  - Shared _make_minio_cache_wrapper helper eliminates duplicate adapter code
  - Falls through to direct provider fetch when no CloudItem row found
- Add _make_minio_cache_wrapper helper to operations.py (DRY, shared by preview and download)
- Add 5 new tests to test_cloud_cache.py: cache-miss fetches provider, cache-hit skips provider, pin released on hit, pin released on miss, user isolation
- Add 3 new security tests to test_cloud_security.py: preview response excludes object_key, download response excludes object_key, foreign-user IDOR via download blocked
 2026-06-23 16:28:06 +02:00
curo1305 5a9f3a628e docs(14-05): complete cloud analysis processing plan 2026-06-23 16:10:42 +02:00
curo1305 f235d894fb feat(14-05): add Celery cloud analysis task with retry harness (Task 2) 
- Implement tasks/cloud_analysis_tasks.py: sync Celery bridge to async processing
- Broker payload contains IDs only — credentials decrypted in worker (T-14-10)
- _TransientError and _ClassificationRetry sentinels for bounded retry (max=3)
- Auth errors are terminal (not retried); MaxRetriesExceeded writes failure status
- celery_app.py: add cloud_analysis_tasks route and import registration
- Add 6 contract tests: task registration, broker payload shape, queue routing,
  bounded retries, sentinel pattern, connection-not-found graceful drop
 2026-06-23 16:06:07 +02:00
curo1305 cea9980aaf feat(14-05): add cloud analysis processing service (Task 1) 
- Implement services/cloud_analysis_processing.py with full pipeline:
  queued -> downloading -> extracting -> classifying -> indexed
- Stale guard: version key comparison fires before provider byte fetch (T-14-13)
- Cache pin lifecycle: pin acquired before bytes used, released in finally block (T-14-12)
- No provider mutation methods called: adapter only used via get_object (T-14-03)
- No local Document row created: classification targets CloudItem directly
- Cooperative cancellation check at job/item level before each stage
- ProcessingResult dataclass with status, cache_entry_id, error_code fields
- Add 4 contract tests: status_transitions, stale_detection, pin_release, no_mutations
 2026-06-23 16:02:44 +02:00
curo1305 1ae9930ca7 docs(14-04): complete analysis orchestration and API plan 2026-06-23 15:54:49 +02:00
curo1305 ba48d625dd feat(14-04): add analysis API routes and typed schemas 
- POST /analysis/connections/{id}/estimate: scope estimate without bytes (T-14-04)
- POST /analysis/connections/{id}/jobs: enqueue job, returns job_id (ANALYZE-01)
- GET /analysis/jobs, GET /analysis/jobs/{id}: job status list and detail
- POST /analysis/jobs/{id}/cancel: batch cancel (queued items immediate; running cooperative)
- POST /analysis/jobs/{id}/items/{item_id}/cancel|skip|retry: per-item controls (ANALYZE-05)
- AnalysisEstimateRequest/Out, AnalysisEnqueueRequest/Out, AnalysisJobOut: typed schemas
- AnalysisJobOut: both simple (waiting/working/done/skipped/failed) and per-stage counts
- All routes use get_regular_user — admin blocked (T-14-01)
- Response schemas exclude credentials_enc, object_key, raw provider URLs (T-14-02)
- 14/14 test_cloud_analysis_api.py pass; 7 new analysis security tests pass (33/33 total)
 2026-06-23 15:50:37 +02:00
curo1305 3f26cd2059 feat(14-04): add cloud_analysis orchestration service 
- estimate_scope: file/selection/folder/connection scope from cached metadata only
- enqueue_analysis_job: create CloudAnalysisJob + items; already_current skip without bytes
- already_current detection: indexed analysis_status + live metadata check (metadata-only, T-14-04)
- cancel_job, cancel_job_item, skip_job_item, retry_job_item: full control operations
- check_scan_quota: seam for future tier enforcement (always True in Phase 14)
- _is_supported: content type + extension list; explicit unsupported-override for .exe etc
- get_adapter / resolve_provider_metadata: stubs for Plan 05 provider integration
- No provider mutation methods called (T-14-03); no bytes downloaded (T-14-04)
- 16/16 test_cloud_analysis_contract.py tests pass
 2026-06-23 15:50:24 +02:00
curo1305 4e02b04ba8 docs(14-03): complete cache service and API plan 2026-06-23 15:36:24 +02:00
curo1305 299d4b523d feat(14-03): cache settings/status API and security tests 
- api/cloud/cache.py: GET /analysis/cache, PATCH /analysis/cache/settings
- api/cloud/analysis.py: analysis router aggregator (Phase 14 parent)
- schemas.py: CacheStatusOut, CacheSettingsUpdateRequest (explicit allowlists)
- __init__.py: register analysis_router under /api/cloud
- 7 new security tests: admin block, unauthenticated block, object_key exclusion,
  response structure, enum validation, tier cap enforcement (T-14-01..02, T-14-08)
- All 47 plan target tests pass (test_cloud_cache.py + test_cloud_security.py)
 2026-06-23 15:32:12 +02:00
curo1305 5bdd23f3bc feat(14-03): add cache orchestration functions and tests 
- retain_or_reuse_cache_entry: reuse non-evicted entry or reactivate evicted row
- pin_cache_entry / release_cache_entry: pin_count lifecycle management
- update_cache_access: touch last_accessed_at for LRU ordering
- Ownership assertions in all new service functions (T-14-06)
- 9 new integration tests covering retain/reuse, pin/release, and isolation
 2026-06-23 15:24:13 +02:00
curo1305 54cc78eb96 docs(14-02): complete Phase 14 Plan 02 — schema and service helpers 
- 14-02-SUMMARY.md: documents migration 0007, ORM models, version-key
  precedence helper, settings service, and Phase 14 cache functions
- STATE.md: advance to Plan 3 of 9, record P02 metrics and decisions
 2026-06-23 15:17:05 +02:00
curo1305 1df61040c6 feat(14-02): add version-key, settings helpers and Phase 14 cache service functions 
- cloud_analysis_versioning.py: compute_version_key with version>etag>fingerprint
  precedence (D-19); compute_fingerprint helper; content_hash is optional post-
  hydration only (D-20); raises ValueError only, no HTTPException
- cloud_analysis_settings.py: get_or_create_user_analysis_settings (upsert on
  first access), update_user_analysis_settings with enum validation and tier-capped
  cache limit, build_default_settings for API responses; raises ValueError only
- cloud_cache.py: Phase 14 durable cache functions added alongside existing Phase 12
  in-memory TTL cache — create_cache_entry, list_cache_entries (owner-scoped),
  evict_lru_entries (LRU, skips pin_count>0 and active_job_count>0), increment/
  decrement_quota_for_cache (atomic UPDATE pattern); re-exports compute_version_key
  from cloud_analysis_versioning so tests have one import site
 2026-06-23 15:14:19 +02:00
curo1305 fd76d06b3a feat(14-02): add migration 0007 and ORM models for cloud analysis cache schema 
- 0007_cloud_analysis_cache.py: new Alembic migration adding 4 Phase 14 tables
  - cloud_byte_cache_entries: durable MinIO cache with version_key uniqueness,
    pin_count/active_job_count guards, LRU eviction indexes
  - cloud_analysis_jobs: batch job rows (scope_kind, status, aggregate counters,
    provider_bytes_estimate, failure_behavior)
  - cloud_analysis_job_items: per-item idempotency rows (status vocabulary,
    controlled error fields, cache_entry_id, retry_count, version_key fingerprint)
  - user_analysis_settings: per-user preferences (progress_detail, failure_behavior,
    cloud_cache_limit_bytes)
  - Reversible downgrade drops Phase 14 objects only
- db/models.py: CloudByteCacheEntry, CloudAnalysisJob, CloudAnalysisJobItem,
  UserAnalysisSettings ORM models mirroring migration
 2026-06-23 15:06:24 +02:00
curo1305 493d348ba6 docs(14-01): complete Phase 14 Plan 01 red test contract 2026-06-23 15:00:57 +02:00
curo1305andClaude Sonnet 4.6 7f2f570582 test(14-01): add RED frontend tests for analysis queue UX and store actions 
- StorageBrowser.analysis-queue.test.js: row-level Analyze action (D-01),
  toolbar Analyze Selection/Folder/Connection (D-01..03), estimate modal
  with D-03 required fields (supported_count/bytes/unsupported, Start action),
  aggregate progress with simplified/detailed labels (D-05..08), expandable
  queue item list, per-item cancel/retry/skip controls (D-09..10),
  batch Cancel all (D-09), architecture no-parallel-grid guard (CLAUDE.md)
- cloudConnections.analysis.test.js: analysis state existence, translateAnalysisStatus
  single-source (D-06/D-12), API call assertions without credentials (T-14-02),
  cancel/retry/skip action coverage (ANALYZE-05), failure_behavior default=pause_batch
  (D-11), detailedAnalysisProgress preference (D-06), cache limit exposure
  (CACHE-04/D-15), credential-free localStorage guard

Requirements: ANALYZE-01..05, CACHE-04..05
All tests fail against missing Phase 14 implementation — no import errors

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-23 14:56:39 +02:00
curo1305andClaude Sonnet 4.6 f67559c7f0 test(14-01): add RED contract tests for cloud analysis and byte cache (backend) 
- test_cloud_analysis_contract.py: estimate (single/selection/connection/folder),
  already-current skip without byte fetch, changed-etag requeue, no-mutation
  invariant, IDOR/admin-negative access (T-14-01..04), cancel/retry transitions
- test_cloud_cache.py: CloudByteCacheEntry schema, LRU eviction with pin
  protection, quota increment/decrement seam (T-14-05), owner isolation
  (CACHE-05), object-key secrecy (T-14-02), version-key precedence helper
- test_cloud_analysis_api.py: route registration gates, job status shape,
  simplified/detailed progress labels (D-06), skip/cancel controls, scan
  quota seam (D-13), failure_behavior field acceptance, unauthenticated block

Requirements: ANALYZE-01..07, CACHE-03..05
All tests fail against missing Phase 14 modules — no syntax/import errors in tests themselves

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-23 14:56:29 +02:00
curo1305 b528b51881 docs(phase-14): plan selective analysis and byte cache 2026-06-23 14:24:43 +02:00
curo1305 3514fdcf3a docs(workflow): require gsd worktrees before edits 2026-06-23 14:10:41 +02:00
curo1305 fac7721dd9 docs(state): record phase 14 context session 2026-06-23 14:04:48 +02:00
curo1305 d3700e20c4 docs(14): capture phase context 2026-06-23 13:59:53 +02:00
curo1305andClaude Sonnet 4.6 2f00e122d3 docs(phase-13): update VALIDATION.md — all tasks green, wave-0 complete 
Nyquist audit 2026-06-23: 3 gaps found and resolved (open/create-folder/rename
audit writes). All 10 tasks marked green, wave_0_complete: true, status: complete.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-23 08:17:29 +02:00
curo1305andClaude Sonnet 4.6 ed046752e4 test(13): add Nyquist validation — promote 3 xfail audit tests to green 
Implemented write_audit_log calls for open_cloud_file, create_cloud_folder,
and rename_cloud_item in api/cloud/operations.py. Removed xfail markers from
test_cloud_audit.py. All 11 audit tests pass; 360 cloud tests pass total.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-23 08:17:24 +02:00
curo1305andClaude Sonnet 4.6 fd48c5b928 docs(phase-13): add security threat verification — 34/34 threats CLOSED 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-23 07:52:31 +02:00
curo1305 0c4f9ccba3 test(13): persist human verification items as UAT 2026-06-23 07:41:48 +02:00
curo1305 40b1572582 test(13): persist human verification items as UAT 2026-06-23 00:43:01 +02:00
curo1305 f92270fda4 test(13): persist human verification items as UAT 2026-06-23 00:42:48 +02:00
curo1305 b1a9f436c4 fix(13): WR-06 read result.status (not result.state) in testConnection to reflect actual server field name 2026-06-23 00:30:01 +02:00
curo1305 60df8552b5 fix(13): CR-05 commit audit log after write_audit_log in reconnect endpoint so event is not silently lost 2026-06-23 00:29:34 +02:00
curo1305 af0de30e93 fix(13): CR-04 soft-delete CloudItem row on successful cloud delete to prevent orphaned metadata 2026-06-23 00:29:11 +02:00
curo1305 405c7a6610 fix(13): CR-03 wrap post-upload DB block in try/except to handle provider-success/DB-fail divergence 2026-06-23 00:28:34 +02:00
curo1305 a1d1c3ba2e fix(13): CR-02 apply PurePosixPath.name guard in WebDAV upload_file and rename to prevent path traversal 2026-06-23 00:27:52 +02:00
curo1305 d4b2697109 fix(13): CR-01 use RFC 6266 filename*=UTF-8'' encoding in Content-Disposition to prevent header injection 2026-06-23 00:26:59 +02:00
curo1305 ebc74f4abe fix(13): CR-06 re-raise HTTPException in preview_cloud_file instead of masking as unsupported_preview 2026-06-23 00:26:23 +02:00
curo1305 fcb38c50b1 docs(13): add code review report 2026-06-23 00:24:20 +02:00
curo1305 cd5bd82260 docs(13-11): update ROADMAP.md via gsd roadmap.update-plan-progress — Phase 13 11/11 summaries verified 2026-06-23 00:19:40 +02:00
curo1305 f09387a9d4 docs(13-11): add self-check result to summary 2026-06-23 00:18:52 +02:00
curo1305 25cc2537bb docs(13-11): complete Phase 13 closeout plan summary and state update 
- 13-11-SUMMARY.md: gate evidence (766 backend + 429 frontend tests pass, bandit 0 HIGH, npm audit clean, gitleaks 3 pre-existing), version 0.3.0, phase complete
- STATE.md: Phase 13 marked complete, progress updated, key decisions carried forward
 2026-06-23 00:18:31 +02:00
curo1305 e68faf3051 chore(13-11): bump to v0.3.0, update docs, roadmap, and Phase 13 security gate evidence 
- Version bump: 0.2.6 → 0.3.0 (Phase 13 complete — full cloud mutation surface shipped)
- CLAUDE.md: update current-state, shared module map, and Phase 13 non-negotiable rules
- README.md: add cloud file management, connection health, and authorized preview features; add Phase 13 mutation API table; mark Phase 13 complete
- ROADMAP.md: mark Phase 13 11/11 plans complete
- SECURITY.md: add Phase 13 threat register (T-13-01 through T-13-34), gate evidence (766 backend + 429 frontend tests pass, bandit 0 HIGH, npm audit 0 high/critical, gitleaks 3 pre-existing)
 2026-06-23 00:14:57 +02:00
curo1305 e809df9f51 docs(13-10): complete frontend health UX and rendered-flow plan summary 2026-06-22 23:59:08 +02:00
curo1305 a7e55d1bb0 feat(13-10): reactive mock store in rendered-flow test surfaces health banner and no-probe assertions 
- CloudFolderRenderedFlow.test.js: mock store uses Vue refs so folderFreshness propagates
  reactively to StorageBrowser via CloudFolderView's template binding (D-12 GREEN)
- setBrowseState in mock now updates _mockFolderFreshness so cloud-health-banner appears
  when API returns warning freshness (T-13-30 mitigated)
- Added testCloudConnection to API mock so D-13 no-probe assertion can verify it was not called
- beforeEach resets reactive refs for test isolation
- 11 rendered-flow tests pass; 70 total across health/store/view/rendered-flow suites
 2026-06-22 23:56:13 +02:00
curo1305 60afb028bf feat(13-10): store-backed health mapping, reconnect UX, no-probe-on-navigation, and Google Drive consent copy 
- D-12: connectionHealth ref as single source for browser compact status and Settings diagnostics
- D-13: handleHealthFailure schedules pendingHealthRetest; navigation never triggers probe
- D-13: testConnection method in store (explicit action only, not navigation side-effect)
- D-14: markReconnecting preserves cached browseItems as stale; markReconnectRefreshPending flag
- D-15: degraded vs requires_reauth health states distinguished in store vocabulary
- D-17: Google Drive scope notice in SettingsCloudTab for all connect/reconnect paths
- StorageBrowser: cloud-health-banner (warning/stale) and requires-reauth prompt with reconnect action
- 59 tests passing: store, Settings, and CloudFolderView health/reconnect suites
 2026-06-22 23:55:58 +02:00
curo1305 a77b7324aa docs(13-09): complete move and delete mutation plan summary 2026-06-22 20:04:38 +02:00
curo1305 508d27643b feat(13-09): move stale-guard, descendant safety, reconciliation, delete disclosure, and metadata-only auditing 
Move endpoint (D-07, D-08, D-09, T-13-27, T-13-28, T-13-29):
- Descendant destination detection via cloud_items ancestor-chain walk (D-09)
- Stale provider result marks source folder non-fresh, returns typed stale body (D-07)
- Success: upsert_cloud_item with new parent_ref before returning
- Success: update_folder_state for both source and destination folders
- Success: write_audit_log 'cloud.item_moved' with metadata-only payload

Delete endpoint (D-10, D-11, T-13-29):
- Pre-fetch item kind for D-10 folder-vs-file disclosure
- Success: update_folder_state for parent folder before returning
- Success: write_audit_log 'cloud.item_deleted' with delete_kind metadata
- Response carries is_folder/item_kind for frontend disclosure
- Failed deletes never emit audit rows

Promote xfail markers in test_cloud_audit.py for move and delete audit rows
 2026-06-22 20:02:09 +02:00
curo1305 af7d45f3c4 test(13-09): add failing RED tests for move stale-guard, reconciliation, and delete disclosure/audit 
- Move: stale etag returns 409 + refreshes source folder state
- Move: descendant destination rejected (D-09)
- Move: success upserts cloud_item with new parent_ref (reconcile-before-return)
- Move: success marks source + destination folders non-fresh
- Move: success writes metadata-only 'cloud.item_moved' audit row
- Delete: success marks parent folder non-fresh
- Delete: folder disclosure stronger than file (is_folder=True, D-10)
- Delete: success writes metadata-only 'cloud.item_deleted' audit row
- Delete: failed delete must not write false audit event
 2026-06-22 19:58:00 +02:00
curo1305 3e9355f42d docs(13-08): complete create-folder and rename collision, stale guard, reconciliation plan summary 2026-06-22 19:53:24 +02:00
curo1305 aaa63c19e4 feat(13-08): implement create-folder and rename collision retry, stale guard, and reconciliation 
- create_cloud_folder: bounded collision retry (up to 5 attempts) with keep_both_name counter suffix (D-05, D-06)
- create_cloud_folder: stale precondition marks parent folder non-fresh and returns typed stale result (D-07)
- rename_cloud_item: stale precondition marks parent folder non-fresh via folder state update (D-07)
- create_cloud_folder: reconcile-before-return upserts new folder in cloud_items and invalidates parent (T-13-26)
- rename_cloud_item: reconcile-before-return upserts renamed item and invalidates parent folder (T-13-26)
- Import upsert_cloud_item, update_folder_state, keep_both_name, CloudResource from service modules
 2026-06-22 19:51:57 +02:00
curo1305 9ad99461bf test(13-08): add RED tests for create-folder and rename collision retry, stale guard, and reconciliation 
- Test 1: collision auto-retry with bounded window (D-05, D-06)
- Test 2: stale guard updates folder state and returns typed stale kind (D-07)
- Test 3: create-folder and rename success upserts CloudItem and invalidates parent folder
- Test 4: failed rename does not mutate CloudItem rows
 2026-06-22 19:49:41 +02:00
curo1305 561a40908d docs(13-07): complete cloud queue and preview plan summary 2026-06-22 19:45:55 +02:00
curo1305 3351e63458 feat(13-07): wire binary-only preview and authorized download through shared actions 
- CloudFolderView: onFileOpen calls openCloudFile(connectionId, provider_item_id, file) — never window.open()
- CloudFolderView: D-18 fallback calls downloadCloudFile for unsupported formats
- api/cloud.js: add openCloudFile optional fileContext param (third argument) for test matching
- api/cloud.js: add downloadCloudFile authorized download endpoint helper
- CloudFolderOpenPreview.test.js: fix makeBrowserStub missing name (findComponent by name)
- All 8 preview suite tests pass — binary-only preview + authorized fallback download
 2026-06-22 19:42:48 +02:00
curo1305 e7e62bbab8 feat(13-07): implement sequential cloud upload queue with typed pause/resume 
- StorageBrowser: add conflict dialog (D-03) and error dialog (D-04) for paused queue states
- StorageBrowser: add upload-queue-resolve emit for Keep both / Replace / Skip / Retry / Cancel all actions
- StorageBrowser: add upload-queue-list with upload-queue-item rows for remaining queued items
- StorageBrowser: suppress UploadProgress in cloud mode (replaced by queue dialogs)
- CloudFolderView: replace placeholder onFilesSelected with sequential queue runner
- CloudFolderView: handle upload-queue-resolve events for all conflict/error resolution actions
- api/cloud.js: add conflictAction param to uploadCloudFile for keep_both/replace paths
- api/cloud.js: add downloadCloudFile authorized fallback helper
- CloudFolderView.test.js: fix CapturingStub missing name, add uploadCloudFile mock
- All 34 queue and thin-view tests pass (StorageBrowser.cloud-queue + CloudFolderView)
 2026-06-22 19:42:29 +02:00
curo1305 fc28e032be docs(13-06): complete upload follow-through plan 2026-06-22 19:31:38 +02:00
curo1305 d959e0cf42 feat(13-06): emit metadata-only audit rows on authoritative upload success 
- Write cloud.file_uploaded audit row in same transaction as reconciliation
- Audit payload is metadata-only: filename, size_bytes, connection_id, provider_item_id, parent_ref
- No provider URLs, tokens, bytes, or document text in audit metadata (T-13-02)
- Non-success paths (conflict, offline, reauth_required) bypass audit write (T-13-21)
- Import get_client_ip from deps.utils and write_audit_log from services.audit
 2026-06-22 19:29:46 +02:00
curo1305 33f0498503 test(13-06): add failing upload audit test (RED) — promote from xfail 
- Remove xfail marker from test_upload_success_writes_metadata_only_audit_row
- Add mock adapter so test isolates audit write logic without real provider I/O
- Test expects cloud.file_uploaded audit row with metadata-only payload (T-13-20)
 2026-06-22 19:28:11 +02:00
curo1305 7ecbec7df9 feat(13-06): route upload success through centralized reconciliation before returning 
- Upsert uploaded item into cloud_items for stable row identity and navigation
- Invalidate parent folder state (warning/upload_mutated) so next browse re-fetches
- Reconcile-before-return: session committed before response returned
- Failed/conflict uploads bypass reconciliation path (T-13-19)
 2026-06-22 19:26:41 +02:00
curo1305 4cd6499a96 test(13-06): add failing upload reconciliation tests (RED) 
- test_upload_success_upserts_cloud_item_before_returning — verifies CloudItem row exists after success
- test_upload_success_marks_folder_freshness_stale — verifies folder state updated on success
- test_upload_failed_does_not_mutate_cloud_items — verifies failed uploads don't create phantom items
 2026-06-22 19:25:47 +02:00
curo1305 cad5ef5de2 docs(13-05): complete upload mechanics plan 2026-06-22 19:22:40 +02:00
curo1305 3ddf4da6a8 feat(13-05): add typed upload route mechanics tests (Task 2) 
- test_upload_success_returns_typed_uploaded_body: kind/provider_item_id/name/size
- test_upload_provider_retryable_error_returns_offline_kind: typed offline body
- test_upload_provider_conflict_returns_conflict_kind: provider-detected collision
- test_upload_reauth_result_is_typed_and_not_500: CONN-02 credential failure path
- test_upload_queue_control_semantics_are_backend_authored: all 4 queue fields
- test_upload_keep_both_name_format: route can use keep_both_name() from service
- test_upload_foreign_user_blocked: IDOR protection on upload route
- 7 new tests pass; full suite 741 passed
 2026-06-22 19:20:18 +02:00
curo1305 e1ce4cbe14 feat(13-05): implement keep_both_name() for D-03/D-05 collision naming 
- keep_both_name(filename, counter) inserts counter before first extension
- Handles compound extensions (archive.tar.gz → archive (1).tar.gz)
- Handles extensionless files (README → README (1))
- Lives in services/cloud_operations as shared upload-queue helper
- All 23 upload contract + keep-both naming tests pass
 2026-06-22 19:17:59 +02:00
curo1305 f47e36d93d test(13-05): add failing RED tests for upload conflict semantics and keep-both naming 
- TestUploadConflictSemantics: typed upload results across all 4 providers
- TestKeepBothNaming: keep_both_name() helper with counter before extension
- Tests verify credentials never appear in upload results (T-13-17)
- Upload kind values must be MUT_KINDS constants
- 16/23 pass (providers already have upload_file); 7 fail (keep_both_name missing)
 2026-06-22 19:17:13 +02:00
curo1305 86a4fe0847 docs(13-04): complete authorized cloud mutations plan 2026-06-22 19:12:20 +02:00
curo1305 94a0617b9b feat(13-04): add authorized cloud content and mutation routes with typed bodies 
- backend/api/cloud/operations.py: owner-scoped open, preview, download, create-folder,
  rename, move, delete, upload routes with typed kind/reason response bodies (D-02, D-03,
  D-05, D-07, D-08, D-09, D-10, D-11, D-18, T-13-01, T-13-14)
- backend/api/cloud/__init__.py: register operations_router on /api/cloud
- backend/api/cloud/connections.py: Google Drive OAuth scope broadened to 'drive' (D-17)
- backend/api/cloud/schemas.py: ConnectionHealthOut, ReconnectOut, ContentResultOut,
  MutationResultOut, CreateFolderRequest, RenameItemRequest, MoveItemRequest typed schemas
- frontend/src/api/cloud.js: centralized helpers for all Phase 13 routes
- backend/tests/test_cloud_mutations.py: mock adapter + settings key fixture; 21 tests pass
- backend/tests/test_cloud_audit.py: mark 6 RED audit tests as xfail (audit writes are
  T-13-05 scope for a later plan); update credential fixture to use settings key
 2026-06-22 19:09:38 +02:00
curo1305 5c0bc2a3b4 feat(13-04): upgrade Google Drive scope to drive, add health/reconnect/content API helpers 
- connections.py: Update Google Drive OAuth to broader `drive` scope (D-17)
  instead of `drive.file` so authorized users can operate on all existing Drive
  items, not just files created by this app. Both initiation and callback flows
  updated to keep scopes consistent.
- schemas.py: Add Phase 13 typed response schemas — ConnectionHealthOut, ReconnectOut,
  ContentResultOut, MutationResultOut, and request schemas CreateFolderRequest,
  RenameItemRequest, MoveItemRequest. All credential-free (T-13-14, CONN-03).
- api/cloud.js: Add centralized frontend helpers for getConnectionHealth,
  reconnectCloudConnection, testCloudConnection (D-12, D-13), plus authorized
  cloud content and mutation helpers: openCloudFile, previewCloudFile,
  createCloudFolder, renameCloudItem, moveCloudItem, deleteCloudItem, uploadCloudFile.

All reconnect/health/test tests pass (14/14). Security suite passes (19/19).
 2026-06-22 18:49:47 +02:00
curo1305 7501036300 docs(13-03): complete cloud operations seam plan 2026-06-22 18:45:54 +02:00
curo1305 6784d3bdb7 feat(13-03): add cloud operations service and reconnect/health/test routes 
- Create backend/services/cloud_operations.py as the single Phase 13 orchestration seam:
  get_connection_health (D-12), test_connection (D-13), reconnect_connection (CONN-01/02/03,
  D-14), disconnect_connection (D-16, explicit CloudItem cascade for SQLite compatibility)
- Add POST /connections/{id}/reconnect route (CONN-01/02/03, D-14)
- Add GET /connections/{id}/health route (D-12, T-13-02)
- Add POST /connections/{id}/test route (D-13, T-13-02)
- Update DELETE /connections/{id} to use service-layer disconnect with explicit
  CloudItem deletion (D-16; covers FK-cascade-less environments like SQLite tests)
- Fix (Rule 2 - T-13-02): add _scrub_audit_metadata() to admin audit log API to
  remove credential fields before returning audit rows to admin callers
- All 14 reconnect tests pass + 110 provider-contract tests pass
- Pre-existing failures in test_cloud_mutations and test_extractor are unrelated
 2026-06-22 18:43:50 +02:00
curo1305 88a62da4c4 feat(13-03): extend cloud contract with mutable adapter and provider implementations 
- Add MutableCloudResourceAdapter abstract class to cloud_base.py with Phase 13
  mutable-operation vocabulary (MUT_KIND_* / MUT_REASON_* constants, PreviewSupport)
- Add abstract methods: create_folder, rename, move, delete, upload_file + _normalize_error
- Update GoogleDriveBackend to implement MutableCloudResourceAdapter with Drive-scope
  methods; prefer trash() for delete (D-11); update SCOPES to drive (D-17)
- Update OneDriveBackend to implement MutableCloudResourceAdapter; use
  PublicClientApplication for refresh_token flow; Graph DELETE is always permanent (D-11)
- Update WebDAVBackend to implement MutableCloudResourceAdapter; SSRF guard via __init__
  (not per-call) for mutable methods; _validate_destination for MOVE SSRF (T-13-04)
- NextcloudBackend inherits all mutable methods from WebDAVBackend (no changes needed)
- Add build_mutable_cloud_adapter() to cloud_backend_factory.py
- All 184 tests pass (test_cloud_backends.py + test_cloud_provider_contract.py)
 2026-06-22 18:31:53 +02:00
curo1305 f2411de85e docs(13-02): complete red frontend test plan for cloud queue, health, and preview 2026-06-22 18:16:47 +02:00
curo1305 8923ed5b3c test(13-02): add red store, health-flow, reconnect, and no-probe tests 
- SettingsCloudTab.health.test.js: Test/Reconnect/Disconnect per-connection actions,
  explicit confirmation before credential removal, Google Drive broader scope consent
  copy (D-12/D-13/D-15/D-16/D-17/T-13-09)
- cloudConnections.test.js: connectionHealth state map, setConnectionHealth translation,
  degraded vs requires_reauth distinction, pendingHealthRetest after failure, reconnect
  preserves cached items, auto-test after connect, no-probe-on-navigation (D-12..D-15)
- CloudFolderRenderedFlow.test.js: warning+reconnect banner alongside cached items,
  requires_reauth renders actionable prompt, folder-navigate never triggers health probe
  (D-12/D-13/D-14/CONN-02/T-13-06)
 2026-06-22 18:13:39 +02:00
curo1305 514925bd4c test(13-02): add red shared-browser queue/preview and thin-view tests 
- StorageBrowser.cloud-queue.test.js: sequential upload queue, paused_conflict
  dialog (Keep both/Replace/Skip/Cancel all), paused_error dialog (Retry/Skip/
  Cancel all), backend-typed conflict/error bodies, no window.open() (D-01/D-03/D-04)
- CloudFolderOpenPreview.test.js: authorized file-open via API, no raw provider
  URLs, Office/Workspace authorized download fallback, no anchor-click download
  hack, no re-emitted file-open to router (D-02/D-18/T-13-07)
- CloudFolderView.test.js: extends thin-view invariants for Phase 13 queue prop
  forwarding and upload-event queue semantics (D-01/D-04)
 2026-06-22 18:10:16 +02:00
curo1305 451d30208c docs(13-01): complete red contract suite plan 2026-06-22 18:03:09 +02:00
curo1305 fd6b561899 test(13-01): extend provider contract suites for four-provider mutable-operation parity 
- Add Phase 13 mutable-operation RED tests to test_cloud_backends.py:
  TestGoogleDriveMutableContract (D-17 scope, create/rename/move/delete/upload),
  TestOneDriveMutableContract (CONN-02 token handoff, permanent-delete disclosure,
  nextLink SSRF guard), TestNextcloudMutableContract (create-folder SSRF, delete
  normalization), TestWebDAVMutableContract (permanent-delete, move SSRF, no
  cloud_items imports)
- Add Phase 13 mutable-operation RED tests to test_cloud_provider_contract.py:
  TestMutableAdapterContract (method existence, async contract, canonical signatures
  for all four providers), TestMutableAdapterResultNormalization (normalized kind/reason
  return types, conflict normalization documentation, unsupported-capability disclosure)
- All new tests fail against the current codebase — mutable adapter methods do not
  exist yet (expected RED); all prior Phase 12 tests remain green
 2026-06-22 18:01:15 +02:00
curo1305 efb596433c test(13-01): add red API and audit contracts for reconnect, content, and mutation flows 
- Create test_cloud_mutations.py: IDOR, admin block, credential secrecy, and typed
  kind/reason body coverage for open, preview, upload, create-folder, rename, move,
  and delete endpoint contracts (D-02 through D-11, D-18)
- Create test_cloud_reconnect.py: reconnect patch-in-place (CONN-01), encrypted credential
  persistence (CONN-02), response secrecy (CONN-03), health endpoint, test action,
  cache-preservation on reconnect (D-14), transient-outage data preservation (D-15),
  and disconnect metadata cleanup (D-16)
- Create test_cloud_audit.py: metadata-only audit rows for every successful cloud operation,
  false-overwrite prevention (T-13-05), admin audit log credential exclusion (T-13-02)
- All tests fail against current codebase — Phase 13 routes do not exist yet (expected RED)
 2026-06-22 17:57:55 +02:00
curo1305 f01bb181c1 docs(state): record phase 13 context session 2026-06-22 15:46:17 +02:00
curo1305 c7688a52f3 docs(13): capture phase context 2026-06-22 15:46:05 +02:00
curo1305 38900e0ee7 test(12.1): complete UAT - 5 passed, 1 issue (missing modified timestamps), 1 skipped 2026-06-22 14:49:01 +02:00
curo1305 64ddb50cd6 fix(cloud): show provider root items in browser 2026-06-22 13:55:07 +02:00
curo1305 d452dee3f7 docs(phase-12.1): update validation strategy 2026-06-22 12:03:16 +02:00
curo1305 b00218e5c5 test(phase-12.1): repair live browse validation guard 2026-06-22 12:03:06 +02:00
curo1305 d02d5db7c3 docs(phase-12.1): audit Nyquist validation coverage 2026-06-22 11:55:31 +02:00
curo1305 66a7937bd1 docs(phase-12.1): add security threat verification 2026-06-22 10:00:09 +02:00
curo1305 aa1d626187 docs(12.1-04): complete plan 04 summary and state updates 2026-06-22 09:48:33 +02:00
curo1305 46b7ea6c12 test(12.1): verify live cloud browse integration 
Phase 12.1 close — docs, version, and security evidence:
- Bump version 0.2.5 → 0.2.6 in backend/main.py, frontend/package.json
- CLAUDE.md: update current state to Phase 12.1 complete v0.2.6
- README.md: add Phase 12.1 corrections, live smoke variable names, Phase 13/14 exclusions
- RUNBOOK.md: add live smoke invocation, warning semantics table, fixture reconciliation procedure
- SECURITY.md: add Phase 12.1 Plan 04 threat table (T-12.1-16..20, T-12.1-SC) and gate evidence
- 12.1-VALIDATION.md: mark Plan 04 complete with final gate evidence
 2026-06-22 09:46:25 +02:00
curo1305 6d294ea7e6 test(12.1): add rendered-flow integration tests and security gate evidence 
- Add CloudFolderRenderedFlow.test.js: 7 tests mounting real CloudFolderView
  with real StorageBrowser/BreadcrumbBar (only API and router stubbed)
  — mixed root render, opaque-ref folder navigation, breadcrumb lineage,
    warning freshness cached rows, fresh freshness, XSS text escaping
- Update 12.1-VALIDATION.md with Task 3 security gate results:
  bandit 0 HIGH, npm audit 0 critical, no Phase-12.1 gitleaks findings,
  595 backend / 376 frontend tests pass, build clean
 2026-06-22 09:41:36 +02:00
curo1305 1ec5158c65 test(12.1): owner-confirmed expected root manifest 
- Create backend/tests/fixtures/cloud/nextcloud_expected_root.json with
  owner_confirmed: true and corrected 10-item name/kind manifest
- Add test_nextcloud_expected_root_manifest: exact set and kind equality
  against fixture (T-12.1-19 — count-only acceptance blocked)
- Update 12.1-VALIDATION.md: manifest status OWNER CONFIRMED, add
  exact-acceptance row to Nyquist matrix
 2026-06-22 09:35:36 +02:00
curo1305 779b05086b test(12.1-04): add opt-in live Nextcloud smoke test suite 
- backend/tests/test_nextcloud_live.py: three read-only live tests behind
  live_nextcloud marker (adapter root metadata, sanitized diagnostic, connection-ID
  browse as testuser@docuvault.example with IDOR/admin negatives)
- backend/pytest.ini: register live_nextcloud marker; addopts excludes it from
  ordinary runs so CI never contacts Nextcloud without explicit selection
- 12.1-VALIDATION.md: live test contract, commands, skip behaviour, sanitized
  7-of-10 probe result, and threat references T-12.1-16 through T-12.1-20
- Manifest status: unconfirmed — Task 2 exact-name gate pending owner decision
 2026-06-22 09:02:42 +02:00
curo1305 9ef7f81b3f docs(12.1-03): complete plan 03 summary and state updates 2026-06-22 08:55:02 +02:00
curo1305 7bb046ac41 fix(12.1): align cloud browser contract — kind, provider_item_id, server freshness 
Normalized cloud frontend for DocuVault v0.2.5:
- Cloud UI classifies items by kind=folder/file (is_dir removed from all active paths)
- Folder navigation uses provider_item_id (opaque provider ref) — DocuVault id kept for row identity
- Server freshness (refresh_state, last_refreshed_at) mapped verbatim — no browser-clock evidence
- Breadcrumb lineage built from explicit visited nodes — never split(provider_item_id)
- CloudFolderTreeItem: expandable/icon/navigate/loadChildren all use kind and provider_item_id
- Version bump 0.2.4 → 0.2.5
- SECURITY.md: T-12.1-11 through T-12.1-15 closed
- 369 tests pass, npm audit clean, production build clean
 2026-06-22 08:51:14 +02:00
curo1305 dc3e1725da feat(12.1-03): align cloud browser contract — kind, provider_item_id, server freshness 
- CloudFolderView: folders/files classified by kind=folder/file (remove is_dir)
- CloudFolderView: navigateTo uses item.provider_item_id for route param (not item.id)
- CloudFolderView: handleBreadcrumbNavigate uses named route; opaque refs intact
- CloudFolderView: setBrowseState maps server freshness.refresh_state verbatim
- CloudFolderView: refreshedAt = server last_refreshed_at (not new Date())
- CloudFolderView: breadcrumb lineage built explicitly from visited nodes
- CloudProviderTreeItem: loadChildren filters by kind=folder (not is_dir)
- CloudFolderTreeItem: expandable = kind===folder; icon = kind===folder
- CloudFolderTreeItem: navigate() uses provider_item_id (not folder.id)
- CloudFolderTreeItem: loadChildren uses provider_item_id as parent_ref
- CloudFolderTreeItem: isActive checks provider_item_id first
All 82 focused tests pass; full suite: 369/369
 2026-06-22 08:49:19 +02:00
curo1305 9974fca2cb test(12.1-03): add RED tests for server freshness mapping 
- cloudConnections: setBrowseState warning/refreshing/fresh states
- cloudConnections: cached items remain during warning
- cloudConnections: selectConnection clears browse state
- cloudConnections: does_not_use_browser_clock_as_refresh_evidence
- CloudFolderView: maps_server_warning_and_last_success
- CloudFolderView: http_200_does_not_imply_fresh
- CloudFolderView: does_not_use_browser_clock_as_refresh_evidence
- CloudFolderView: cached_items_remain_visible_during_warning
3 new failures against unconditional fresh/new Date() behavior
 2026-06-22 08:45:50 +02:00
curo1305 ba7f652cde test(12.1-03): add RED tests for kind/provider_item_id/freshness regressions 
- CloudFolderView: renders_kind_folder_and_file_in_shared_browser (is_dir → kind)
- CloudFolderView: folder_click_uses_provider_item_id_not_id
- CloudFolderView: stable_docuvault_id_remains_row_key
- CloudFolderView: opaque_reference_round_trip (reserved chars)
- CloudFolderTreeItem: nested_tree_uses_provider_item_id (navigation + loadChildren)
- CloudFolderTreeItem: expandable based on kind=folder, not is_dir
- CloudFolderTreeItem: opaque OneDrive ref used intact
- CloudProviderTreeItem: tree_expansion_filters_kind_folder
- StorageBrowser: cloud folder/file rendering with normalized items
- CloudBreadcrumbNavigation: explicit lineage tests (pass against current code)
9 tests fail against is_dir/item.id behavior as expected
 2026-06-22 08:44:27 +02:00
curo1305 792a25fad7 docs(12.1-02): complete plan 02 summary and state updates 2026-06-22 08:38:18 +02:00
curo1305 70a543a8c1 fix(12.1): make cloud freshness authoritative — plan 02 documentation and version 
- Version bump 0.2.3 → 0.2.4 (user-visible sync status corrected)
- CLAUDE.md: update current state; add apply_listing_and_finalize to module map; add no-independent-fresh rule
- README.md: bump version
- RUNBOOK.md: update freshness state docs; explain complete=True gate and last_refreshed_at behavior
- SECURITY.md: add T-12.1-06..10 threat closure evidence for Plan 02
 2026-06-22 08:34:51 +02:00
curo1305 bfa4dc502a feat(12.1-02): centralize listing freshness gate — apply_listing_and_finalize 
- Add ListingResult dataclass to cloud_items.py
- Add apply_listing_and_finalize() — single shared gate for complete/incomplete semantics
- complete=True: upserts, soft-deletes unseen children, marks fresh, advances last_refreshed_at
- complete=False: upserts seen items only, never deletes unseen, preserves prior timestamp, warns
- browse.py: replace unconditional update_folder_state('fresh') with apply_listing_and_finalize
- cloud_tasks.py: replace unconditional fresh transition with apply_listing_and_finalize
- Celery task returns structured warning status on incomplete (no credentials/provider item names)
- Fix timezone naive/aware comparison in test (SQLite strips tzinfo)
 2026-06-22 08:29:41 +02:00
curo1305 fe08afd740 test(12.1-02): add failing tests for truthful freshness gate (RED) 
- test_incomplete_listing_never_marks_folder_fresh
- test_incomplete_listing_retains_cached_rows_and_last_success
- test_complete_empty_listing_is_authoritative_and_fresh
- test_partial_items_upsert_without_deleting_unseen_children
- test_apply_listing_returns_warning_for_complete_false
- test_sync_browse_returns_warning_for_complete_false
- test_worker_returns_warning_for_complete_false
- security: browse_complete_false_never_sets_fresh, no_raw_provider_error, owner_scoped_on_incomplete
 2026-06-22 08:26:35 +02:00
curo1305 a6e8a597e7 docs(12.1-01): complete Plan 01 summary and state updates 2026-06-22 08:20:06 +02:00
curo1305 62128730e8 fix(12.1-01): restore asyncio import, bump version to 0.2.3, update docs 
- Restore asyncio import removed when legacy list_folder was deleted (health_check
  still uses asyncio.to_thread); fixes test_nextcloud_connect_persists regression
- Bump backend/main.py and frontend/package.json version to 0.2.3
- Update CLAUDE.md: note Phase 12.1 Plan 01 complete, add normalize_nextcloud_url
  to shared module map, add NextcloudBackend no-override rule
- Update README.md: version 0.2.3, note canonical Nextcloud URL normalization and
  OneDrive nextLink origin guard
- Full backend suite: 585 passed, 1 pre-existing failure (missing python-docx module)
 2026-06-22 08:18:23 +02:00
curo1305 805fe44bfb feat(12.1-01): add cross-origin nextLink guard and Drive/OneDrive contract tests 
- Validate @odata.nextLink hostname against graph.microsoft.com before following
  (T-12.1-03); cross-origin nextLink returns complete=False with prior items retained
- Add TestOneDriveCrossOriginNextLink: cross-origin rejection, same-origin follows,
  page failure retains prior items
- Add TestGoogleDriveAuthFailureControl: 401 returns complete=False, page1+page2
  error retains page1 items
- All 163 four-provider contract tests pass
 2026-06-22 08:12:39 +02:00
curo1305 2b46f74329 feat(12.1-01): repair Nextcloud adapter contract and add URL normalization 
- Remove incompatible NextcloudBackend.list_folder(folder_path="") override
  so Nextcloud inherits canonical WebDAVBackend.list_folder(connection_id,
  user_id, parent_ref=None, page_token=None) -> CloudListing
- Add normalize_nextcloud_url() to cloud_utils.py: idempotent canonical DAV
  root derivation, username percent-encoding, https-only, rejects userinfo/
  query/fragment, validates via SSRF guard before return
- Use normalize_nextcloud_url in cloud_backend_factory for nextcloud provider
- Add TestNextcloudBackendNoListFolderOverride and TestNextcloudUrlNormalization
  to test_webdav_backend.py
- All 9 Nextcloud contract failures now pass; full focused suite: 158 passed
 2026-06-22 08:11:06 +02:00
curo1305 eb68facd6c test(12.1-01): add failing four-provider contract suite and fixtures 
- Create test_cloud_provider_contract.py with parametrized suite for
  Nextcloud, WebDAV, Google Drive, OneDrive
- Assert canonical (connection_id, user_id, parent_ref=None, page_token=None)
  signature, CloudListing return type, trusted caller identity propagation,
  metadata normalization, pagination completeness, and forbidden-operation spies
- Add synthetic credential-free fixtures: nextcloud_root.xml, webdav_root.xml,
  google_drive_pages.json, onedrive_pages.json
- 9 tests fail for nextcloud (expected RED state — incompatible list_folder override)
- All webdav, google_drive, onedrive contract tests pass
 2026-06-22 08:09:00 +02:00
curo1305 692600c755 test(12): close Nyquist validation gap 2026-06-22 06:44:33 +02:00
curo1305 e64980af5f docs(phase-12): add security threat verification — 26/26 closed 2026-06-22 01:39:24 +02:00
curo1305andClaude Sonnet 4.6 c283623903 docs(phase-12): resolve UAT gaps and close phase after 12-06 gap closure 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-21 22:38:23 +02:00
curo1305 bd5e8f4192 docs(12): add code review report for phase 12-06 gap closure 2026-06-21 22:35:01 +02:00
curo1305 4a910549ac docs(12-06): add plan 06 SUMMARY — UUID-only navigation, multi-account, credential-update 2026-06-21 22:30:51 +02:00
curo1305 c85e4abd91 chore(12-06): bump version 0.2.1 → 0.2.2 2026-06-21 22:30:11 +02:00
curo1305 057b4999fd feat(12-06): UUID-only cloud navigation, breadcrumb hierarchy, route-aware sidebar 
- CloudProviderTreeItem: getCloudFoldersByConnectionId(connection.id) + /cloud/{uuid}/root
- CloudFolderTreeItem: connectionId prop replaces provider slug in browse + route
- AppSidebar: Cloud Storage active only on exact /cloud; connection nodes use per-connection isActive
- New tests: CloudProviderTreeItem, CloudFolderTreeItem, AppSidebar cloud active-state
 2026-06-21 22:30:05 +02:00
curo1305 731b65ecdd feat(12-06): connection-ID native lifecycle — always INSERT, PUT credentials, connectionsFor multi-account 
- Replace _upsert_cloud_connection with _insert_cloud_connection (always inserts new UUID row)
- Add PUT /connections/{id}/credentials endpoint (owner-scoped, SSRF + health-check, password-preserve)
- SettingsCloudTab: connectionsFor() renders all same-provider connections with Add account row
- CloudCredentialModal.submit: calls updateWebDavCredentials on edit, connectWebDav on create
- utils.js: FastAPI validation arrays normalised to concise field messages (Rule 2)
- Backend tests: same-provider independence + IDOR negative test for credential update
 2026-06-21 22:29:59 +02:00
curo1305 97c30c3a15 docs(12): plan cloud UAT gap fixes 2026-06-21 22:21:05 +02:00
curo1305 70ed1219a9 test(12): pause UAT - 1 passed, 2 issues, 3 blocked 2026-06-21 22:18:14 +02:00
curo1305 8c80607df9 fix(dev-env): complete local startup configuration 2026-06-21 20:43:45 +02:00
curo1305 461b56892c docs(12-05): mark VERIFICATION.md passed — all 5 truths verified 2026-06-21 20:33:37 +02:00
curo1305andClaude Sonnet 4.6 206f564248 test(12-05): fix test_nextcloud_connect_persists + compose migration test path 
- test_nextcloud_connect_persists: provider=nextcloud routes to NextcloudBackend
  (not WebDAVBackend) — add storage.nextcloud_backend.validate_cloud_url patch
  and use AsyncMock for asyncio.to_thread (plain return_value=True is not
  awaitable, swallowed by except → False). Test now passes HTTP 201.
- test_compose_migrations: skip module when docker-compose.yml is not found at
  the expected repo-root path (file is not mounted inside the backend container).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-20 12:35:35 +02:00
curo1305andClaude Sonnet 4.6 043a7817e2 fix(12-uat): add display_name_override schema regression + Compose hardening 
- test_list_connections_reads_display_name_override_column: proves GET /api/cloud/connections
  does not raise UndefinedColumn (direct Phase 12 UAT blocker regression)
- docker-compose: promtail socket :ro, Grafana password fail-fast (:?)
- test_migration_0006: DDL privilege test fails not skips when role absent
- README: version 0.2.1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-20 11:07:30 +02:00
curo1305andClaude Sonnet 4.6 760a8d4bcd fix(12-uat): resolve critical code review findings in gap closure (CR-01 through CR-03, IN-01) 
- CR-01: promtail Docker socket mounted :ro (was read-write)
- CR-02: Grafana admin password uses :? fail-fast (was :-changeme default)
- CR-03: DDL privilege test fails not skips when docuvault_app role absent
- IN-01: README version synced to 0.2.1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-20 10:55:23 +02:00
curo1305 b6526e46f1 docs(12): add gap closure code review report 2026-06-20 10:54:22 +02:00
curo1305 bb818e0621 docs(phase-12): resolve UAT gaps and debug sessions after 12-05 gap closure 2026-06-20 10:51:44 +02:00
curo1305 34be364ca7 docs(phase-12): update tracking after gap closure wave 2026-06-20 10:50:38 +02:00
curo1305 824d271a42 chore: merge executor worktree (worktree-agent-a724010d4b729caf8) 2026-06-20 10:50:22 +02:00
curo1305 67d3e4bcac docs(12-05): complete gap closure plan SUMMARY 2026-06-20 10:49:59 +02:00
curo1305 3ca57dcd0c fix(12-05): bump version to 0.2.1 and update docs for migration-gated startup 
- backend/main.py, frontend/package.json: version 0.2.0 → 0.2.1
- CLAUDE.md, AGENTS.md: current state updated to reflect gap-closure
- README.md: startup instructions note migrate runs automatically; update migration commands
- RUNBOOK.md: startup diagram includes migrate service; migration gate explanation
- SECURITY.md: Phase 12 gap-closure threat register and security gate evidence
 2026-06-20 10:49:21 +02:00
curo1305 de2efd1664 test(12-05): add migration 0005→0006 integration regression and RUNBOOK migration ops 
- test_migration_0006.py: proves display_name_override, cloud_items, cloud_item_topics,
  cloud_folder_states, unique constraints, indexes, and DDL privilege boundary
- Tests skip cleanly without INTEGRATION=1/INTEGRATION_DATABASE_URL (no dev DB mutation)
- RUNBOOK: add Database Migrations section with revision check, upgrade, recovery, and
  emergency schema-drift remediation commands
 2026-06-20 10:47:11 +02:00
curo1305 1b3084ddfa feat(12-05): add migration-gated Compose startup path 
- Add one-shot migrate service using DATABASE_MIGRATE_URL and alembic upgrade head
- Add migrate dependency (service_completed_successfully) to backend, celery-worker, celery-beat
- migrate service has same read_only/cap_drop/no-new-privileges hardening as other services
- Add test_compose_migrations.py: 7 static assertions on Compose configuration
 2026-06-20 10:45:22 +02:00
curo1305 66d8634b17 docs(12): plan UAT migration gap closure 2026-06-20 10:40:37 +02:00
curo1305 a7e17d69b4 docs(12): add root causes from diagnosis 2026-06-19 23:44:04 +02:00
curo1305 802afebafe test(12): complete UAT - 0 passed, 2 issues 2026-06-19 23:39:22 +02:00
curo1305 13b9d83401 docs(phase-12): update validation strategy 2026-06-19 06:10:55 +02:00
curo1305 33264862c1 docs(phase-12): evolve PROJECT.md and CLAUDE.md after phase completion 2026-06-19 06:06:01 +02:00
curo1305 8e5d7a1900 docs(phase-12): complete phase execution 2026-06-19 06:05:03 +02:00
curo1305andClaude Sonnet 4.6 b6911fb4ed fix(12): resolve critical code review findings (CR-01 through CR-04) 
- CR-01: fix browse URL from /folders/{id} to /items?parent_ref= (broken feature)
- CR-02: remove raw provider exception text from _TerminalProviderError messages
- CR-03: add user_id predicate to get_or_create_folder_state query (ownership boundary)
- CR-04: add max_length=255 to ConnectionRenameRequest.display_name

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-19 02:00:05 +02:00
curo1305 de63e2a3a4 docs(12): add code review report 2026-06-19 01:59:17 +02:00
curo1305 b7ae44b3f8 docs(phase-12): update tracking after wave 4 2026-06-19 01:55:47 +02:00
curo1305 06ccc865b9 chore: merge executor worktree (worktree-agent-aa3d7c2b49ba82638) 2026-06-19 01:55:35 +02:00
curo1305 7b1fc6e5cf docs(12-04): create Phase 12 Plan 04 SUMMARY.md 
Records security-negative suite completion, threat register closure, gate
evidence, version bump to 0.2.0, and D-01..D-18 decision coverage map.
 2026-06-19 01:55:15 +02:00
curo1305 c441fc63e5 chore(12-04): bump version to 0.2.0 and finalize Phase 12 documentation 
- backend/main.py, frontend/package.json: 0.1.6 → 0.2.0 (phase-complete minor bump)
- AGENTS.md: current state updated to Phase 12 complete; cloud-resource-foundation
  summary with browse contract, security suite, and Phase 13/14 boundary note
- README.md: version updated to 0.2.0
- All existing shared module map rules and frontend architecture constraints unchanged
 2026-06-19 01:54:24 +02:00
curo1305 fccb9c6394 security(12-04): add Phase 12 security gate evidence and cloud ops runbook 
- SECURITY.md: Phase 12 threat register (T-12-01 through T-12-SC) with
  evidence for all 8 threat IDs; bandit/npm audit gate results;
  accepted risks for pip-audit tooling gap and DISABLED connection behavior
- RUNBOOK.md: Phase 12 cloud operations section covering connection
  management, browse refresh lifecycle, item metadata queries,
  stuck-refresh recovery, and security operation notes
 2026-06-19 01:52:49 +02:00
curo1305 3b24058e15 test(12-04): add dedicated cloud security-negative integration suite 
- test_foreign_user_cannot_browse_cloud_item (IDOR T-12-01, CONN-04)
- test_admin_cannot_browse_cloud_connection (admin block T-12-01, D-03)
- test_browse_response_excludes_credentials_and_raw_fields (T-12-03, D-06)
- test_ssrf_url_validation_invariants (T-12-04, D-14)
- test_browse_no_quota_mutation (T-12-09, D-07)
- test_browse_no_minio_calls (T-12-09, D-08)
- test_disabled_connection_browse_blocked (D-17)
- test_same_provider_items_scoped_to_connection (D-01, D-05 PostgreSQL)
- test_no_byte_download_during_browse (D-18)
- 16 tests pass; full suite 509 passed
 2026-06-19 01:51:13 +02:00
curo1305 8a99230048 docs(phase-12): update tracking after wave 3 2026-06-18 23:33:03 +02:00
curo1305 84c2549c36 chore: merge executor worktree (worktree-agent-a280818c01e94acd2) 2026-06-18 23:32:56 +02:00
curo1305 5287efd34c docs(12-03): add plan 03 execution summary 2026-06-18 23:32:41 +02:00
curo1305 c6c0742267 feat(12-03): breadcrumb freshness, formatRelativeTime, v0.1.6, docs 
- BreadcrumbBar: refreshing spinner, fresh checkmark (fades 3s), stale warning banner
- Accessible labels and role=status for all freshness states
- formatters.js: add formatRelativeTime (shared, no duplication)
- Version bump 0.1.5 → 0.1.6 in backend/main.py and frontend/package.json
- AGENTS.md: update state, shared module map (formatRelativeTime)
- README.md: unified connection-root browsing and capability explanations feature text
- 17 BreadcrumbBar tests pass; 323 total; production build clean
 2026-06-18 23:31:50 +02:00
curo1305 44244335a1 feat(12-03): capability-aware action rendering in StorageBrowser 
- Add capabilities, connectionRoot, folderFreshness, lastRefreshedAt, byteAvailability props
- CapabilityButton inline component: aria-disabled, click/Enter/Space/touch suppression
- Gray for unsupported, amber for temporarily_unavailable — no native disabled
- Local defaults preserve all pre-Phase-12 drag/share/move/delete behavior
- Cached-byte marker (clock icon) on size column when byteAvailability='cached'
- No marker for cloud_only
- AppIcon: add info, clock icons
- 50 StorageBrowser tests pass
 2026-06-18 23:29:10 +02:00
curo1305 bf9af11274 feat(12-03): connection-ID routing, rename, session folder memory, thin views 
- Route /cloud/:connectionId/:folderId replaces /cloud/:provider/:folderId
- api/cloud.js: getCloudFoldersByConnectionId + renameCloudConnection
- cloudConnections store: rename, selectConnection, setBrowseState, defaultDisplayName, session storage helpers
- CloudStorageView: thin — passes connectionRoots to StorageBrowser
- CloudFolderView: thin — uses connectionId param, never provider slug
- SettingsCloudTab: inline rename input for each active connection
- 27 tests pass: store, view, settings
 2026-06-18 23:25:29 +02:00
curo1305 6f0ecfa39b docs(phase-12): update tracking after wave 2 2026-06-18 23:19:55 +02:00
curo1305 81c4d52041 chore: merge executor worktree (worktree-agent-ac074b0ec7fc0dbc3) 2026-06-18 23:19:27 +02:00
curo1305 f61736621e chore: track AGENTS.md (untracked file blocking wave-2 merge) 2026-06-18 23:19:05 +02:00
curo1305 e5d6b9ea53 docs(12-02): execution summary — CloudResourceAdapter, browse endpoint, Celery refresh task 2026-06-18 23:18:30 +02:00
curo1305 c6237ca57f feat(12-02): add refresh_cloud_folder Celery task, staleness trigger, version 0.1.5 
- Add tasks/cloud_tasks.py: durable refresh_cloud_folder task with 3-retry
  bounded backoff (30s/90s/270s +jitter), credential decryption in worker only
- Register tasks.cloud_tasks.* on documents queue in celery_app.py
- Add stale-while-revalidate staleness trigger in browse.py (5-min threshold)
- Add 4 Task 3 tests: idempotency, cached-row retention on failure, task structure,
  no-byte-download contract; add background-refresh scheduling integration test
- Bump backend version 0.1.4 → 0.1.5, frontend package.json 0.1.4 → 0.1.5
- Update AGENTS.md with Phase 12 Plan 02 state and new shared module map entries
- Update README with connection-ID browse API table and v0.1.5
 2026-06-18 23:17:34 +02:00
curo1305 e186019066 feat(12-02): decompose api/cloud.py into package with connection-ID browse endpoint 
- Add api/cloud/ package: connections.py, browse.py, schemas.py, __init__.py
- Add GET /api/cloud/connections/{connection_id}/items (T-12-01 IDOR, T-12-03 cred-free)
- Add PATCH /api/cloud/connections/{id} for display_name_override rename
- Add display_name_override ORM field to CloudConnection model
- Add CloudResourceAdapter service layer with str/UUID coercion
- Fix UUID type compatibility: test_cloud_items.py now uses UUID(as_uuid=True)
  matching conftest — removes String(36) patch that caused type incompatibility
- Add 11 Phase 12 integration tests (IDOR, admin block, credential exclusion,
  duplicate providers, rename, malformed UUID)
- Remove deleted api/cloud.py (replaced by api/cloud/ package)
 2026-06-18 23:10:30 +02:00
curo1305 ff33439f0a feat(12-02): normalize all four providers into CloudResourceAdapter contract 
- GoogleDriveBackend: list_folder with full pagination, native doc size=None, get_capabilities
- OneDriveBackend: list_folder with @odata.nextLink pagination, get_capabilities
- WebDAVBackend: list_folder via PROPFIND with SSRF re-validation, get_capabilities
- NextcloudBackend: inherits CloudResourceAdapter from WebDAVBackend
- build_cloud_resource_adapter() added to factory
- 22 new contract/behavior/pagination/no-byte-download tests (51 total pass)
 2026-06-18 22:45:09 +02:00
curo1305 71ba0293a5 docs(phase-12): update tracking after wave 1 2026-06-18 22:39:35 +02:00
curo1305 312a96d2bf chore: merge executor worktree (worktree-agent-a032d981c3b3ec11b) 2026-06-18 22:39:06 +02:00
curo1305 3127853c1e docs(12-01): complete cloud-resource-foundation plan 01 summary 2026-06-18 22:38:46 +02:00
curo1305 718fb2c2b5 feat(12-01): durable owner-scoped cloud metadata schema (migration 0006 + models) 
- Migration 0006: cloud_items, cloud_item_topics, cloud_folder_states tables
- cloud_connections: add display_name_override column for same-provider disambiguation
- CloudItem, CloudItemTopic, CloudFolderState ORM models with owner/connection indexes
- Unique (connection_id, provider_item_id) boundary; no MinIO object_key field
- Root folder state representable as parent_ref='' without CloudItem parent row
- services/cloud_items.py: resolve_owned_connection, upsert, list, reconcile, folder state
- 17 unit/integration tests covering model fields, isolation, quota invariant, idempotency
 2026-06-18 22:37:28 +02:00
curo1305 0a7273b9fe feat(12-01): normalized cloud resource capability contract and unit tests 
- Define 9 action keys, 3 capability states, 6 reason codes in cloud_base.py
- Immutable CloudCapability, CloudResource, CloudListing frozen dataclasses
- Abstract CloudResourceAdapter with list_folder, get_capabilities, merge_item_capabilities
- No mutation methods in Phase 12 interface (Phase 13 boundary enforced)
- 29 unit tests covering vocabulary, validation, merge behavior, fake adapter
 2026-06-18 22:34:23 +02:00
curo1305 11b91775b6 docs(12): create phase plan 2026-06-18 22:30:07 +02:00
curo1305andClaude Sonnet 4.6 fe54a855b3 docs(phase-12): fix UI-SPEC typography and spacing blocking issues 
- Collapse font weights from 3 to 2: drop font-medium (500), use font-semibold (600) for row primary names, labels, column headers; font-normal (400) for body
- Fix sm spacing token usage: replace p-1.5 (6px) with p-2 (8px) to match declared 8px value
- Update health badge in connection root list from font-medium to font-semibold

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-18 22:19:25 +02:00
curo1305andClaude Sonnet 4.6 ea682fdecd docs(phase-12): add UI design contract for cloud-resource-foundation 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-18 22:16:22 +02:00
curo1305 52b110acef docs(phase-12): add research and validation strategy 2026-06-18 22:13:23 +02:00
curo1305 09814c28a9 docs(12): capture phase context 2026-06-18 22:07:26 +02:00
curo1305 a323276e37 docs: create milestone v0.3 roadmap (5 phases) 2026-06-17 23:27:21 +02:00
curo1305 608acedaf6 docs: define milestone v0.3 requirements 2026-06-17 23:24:54 +02:00
curo1305 9150d28fe1 docs: research milestone v0.3 cloud storage integration 2026-06-17 23:19:01 +02:00
curo1305 0e56c85349 docs: start milestone v0.3 Reimagining Cloud Storage integration 2026-06-17 23:16:21 +02:00
curo1305andClaude Sonnet 4.6 123ae5b29b chore: archive v0.2 phase directories to milestones/v0.2-phases/ 
Moves phases 08–11 execution artifacts from .planning/phases/ to
.planning/milestones/v0.2-phases/ to keep .planning/phases/ clean
for the next milestone.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-17 14:34:52 +02:00
279 changed files with 47338 additions and 2584 deletions
Expand all files Collapse all files
.env.example
+18
View File
@@ -17,6 +17,8 @@ POSTGRES_PASSWORD=changeme_super
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=changeme_minio_root
MINIO_ENDPOINT=minio:9000
# Browser-resolvable endpoint used in presigned URLs.
MINIO_PUBLIC_ENDPOINT=localhost:9000
# App-level access key. docker-compose.yml provisions this user and a bucket-scoped policy.
MINIO_ACCESS_KEY=docuvault_app
MINIO_SECRET_KEY=changeme_minio_app
@@ -74,3 +76,19 @@ ONEDRIVE_TENANT_ID=common
# Backend and frontend URLs — used to construct OAuth callback/redirect URLs
BACKEND_URL=http://localhost:8000
FRONTEND_URL=http://localhost:5173
# ── AI Defaults ──────────────────────────────────────────────────────────────
DEFAULT_AI_PROVIDER=ollama
DEFAULT_AI_MODEL=llama3.2
SYSTEM_PROMPT=
# ── Auth/session durations ───────────────────────────────────────────────────
ACCESS_TOKEN_EXPIRE_MINUTES=15
REFRESH_TOKEN_EXPIRE_DAYS=30
REFRESH_TOKEN_EXPIRE_HOURS=16
# ── Development logging and observability ────────────────────────────────────
LOG_LEVEL=INFO
LOG_JSON=true
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=CHANGEME-replace-with-strong-password
.planning/PROJECT.md
+24 -4
View File
@@ -14,6 +14,18 @@ Every user's documents — and the credentials they use to store them — are in
See `.planning/MILESTONES.md` and `.planning/milestones/v0.2-ROADMAP.md` for full archive.
## Current Milestone: v0.3 Reimagining Cloud Storage integration
**Goal:** Make connected cloud storage behave like first-class DocuVault storage: users can browse and manage cloud files as if they were local, analyze all or selected cloud documents, and search them by keywords, sentences, or ideas while minimizing DocuVault-owned local storage.
**Target features:**
- Native-feeling cloud file navigation and actions: open, preview, upload, move, delete, rename, and organize files from connected providers.
- Provider setup, health, reconnect, credential lifecycle, and error handling that make cloud connections feel reliable and understandable.
- Analyze all cloud documents or a selected subset without requiring manual local upload.
- Classify and index cloud documents so they become smart-searchable like locally uploaded documents.
- Cache and offload cloud file bytes on demand, similar to a desktop sync client, preserving local-like navigation while minimizing local storage use.
- Rework storage architecture where needed: provider capabilities, background jobs, sync/import/index state, conflict handling, and test coverage.
## Requirements
### Validated (v0.1 — shipped 2026-06-06)
@@ -65,7 +77,14 @@ See `.planning/MILESTONES.md` and `.planning/milestones/v0.2-ROADMAP.md` for ful
- ✓ Dead code deleted (FolderRow.vue, AccountView.vue, stale test files) — v0.2
- ✓ WHY-only comment policy enforced (CODE-09) — v0.2
### Active (next milestone — not yet defined)
### Active (v0.3 — Reimagining Cloud Storage integration)
- [ ] Cloud files can be browsed and managed with the same core actions as local files: open, preview, upload, move, delete, and rename.
- [ ] Cloud provider setup and maintenance includes health status, reconnect flows, credential lifecycle handling, and useful error states.
- [ ] Users can analyze all cloud documents or a selected subset from connected storage.
- [ ] Analyzed cloud documents are classified and indexed for smart search by keywords, sentences, and semantic ideas.
- [ ] DocuVault minimizes local storage by caching cloud file bytes only when needed and offloading them when safe.
- [ ] Storage architecture models provider capabilities, sync/index state, background jobs, and conflict/error handling explicitly.
### Out of Scope
@@ -79,7 +98,7 @@ See `.planning/MILESTONES.md` and `.planning/milestones/v0.2-ROADMAP.md` for ful
## Context
- **Current state**: v0.2 shipped 2026-06-17. All 4 v0.2 phases complete: stack upgrade + decomposition (Phase 8), admin panel rearchitecture (Phase 9), UX interaction layer (Phase 10), visual design + responsive layout (Phase 11). 277 tests pass. Bundle −81 kB from baseline. App is mobile-responsive, keyboard-navigable, and fully polished. Ready for next milestone definition.
- **Current state**: v0.3 in progress — Phase 12 (cloud-resource-foundation) complete 2026-06-19. Provider-neutral CloudResourceAdapter contract, durable CloudItem/CloudFolderState ORM, connection-ID browse API, stale-while-revalidate Celery refresh task, and capability-aware StorageBrowser frontend all shipped. v0.2.0 released. Phase 13 (cloud mutations: create/rename/move/delete) is next.
- **Tech stack**: FastAPI 0.136+ (Python 3.12), SQLAlchemy 2.0 async, Alembic, MinIO SDK; Vue 3 (Options API), Pinia, Vue Router 4, Vite, Tailwind CSS.
- **Code quality**: v0.1 was built feature-first under time pressure. Both backend and frontend contain duplication, inconsistent patterns, and components that grew beyond their original scope. v0.2 addresses this systematically.
- **Admin panel**: Standalone /admin/* route subtree with AdminLayout as the route component, AdminSidebar with 5 nav links, and 5 dedicated view components. AdminView.vue and legacy tab components deleted. Admin users redirect to /admin on login; non-admin blocked by to.matched.some() guard.
@@ -120,12 +139,13 @@ See `.planning/MILESTONES.md` and `.planning/milestones/v0.2-ROADMAP.md` for ful
| Teleport + getBoundingClientRect for dropdowns | Viewport-edge clipping eliminated without complex position logic; prerequisite for virtual scrolling | ✓ Shipped Phase 10 (UX-13) |
| Admin routes lazy-loaded | All 5 admin views excluded from initial bundle; −81 kB (−30.6%) improvement | ✓ Shipped Phase 11 (PERF-03) |
| Vite 8 upgrade for npm audit | Closed high-severity esbuild CVE present in Vite 5/6; npm audit now clean | ✓ Shipped Phase 11 (11-07) |
| Virtual-local cloud storage model | Users already organize documents in their cloud provider; DocuVault should add local-like actions, analysis, and smart search without forcing full import | — Pending v0.3 |
## Evolution
This document evolves at phase transitions and milestone boundaries.
Last updated: 2026-06-16
Last updated: 2026-06-19
**After each phase transition** (via `/gsd-transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
@@ -141,4 +161,4 @@ Last updated: 2026-06-16
4. Update Context with current state
---
*Last updated: 2026-06-17 — after v0.2 milestone*
*Last updated: 2026-06-17 — after starting v0.3 milestone*
.planning/REQUIREMENTS.md
+136
View File
@@ -0,0 +1,136 @@
# Requirements: DocuVault v0.3
**Defined:** 2026-06-17
**Core Value:** Every user's documents — and the credentials they use to store them — are inaccessible to everyone except that user, while the platform scales horizontally and supports pluggable storage backends.
## v0.3 Requirements
### Connections
- [x] **CONN-01**: User can connect, reconnect, test, and disconnect each supported cloud provider.
- [x] **CONN-02**: User can see connection health and actionable errors for expired, revoked, or invalid credentials.
- [x] **CONN-03**: Reconnecting or refreshing credentials invalidates stale provider caches without exposing credentials.
- [x] **CONN-04**: User interface reflects the file operations supported by each connected provider.
### Cloud File Management
- [x] **CLOUD-01**: User can browse connected cloud files and folders through the shared `StorageBrowser`.
- [x] **CLOUD-02**: User can open and preview supported cloud documents through DocuVault authorization.
- [x] **CLOUD-03**: User can upload files into the currently viewed cloud folder.
- [x] **CLOUD-04**: User can create folders in connected cloud storage where the provider supports it.
- [x] **CLOUD-05**: User can rename cloud files and folders where the provider supports it.
- [x] **CLOUD-06**: User can move files and folders within the same cloud connection where the provider supports it.
- [x] **CLOUD-07**: User can delete cloud files and folders after explicit confirmation.
- [x] **CLOUD-08**: User sees unsupported cloud actions disabled with a provider-specific explanation.
- [x] **CLOUD-09**: Successful cloud mutations update navigation promptly and produce metadata-only audit events.
### Cloud Analysis
- [x] **ANALYZE-01**: User can request analysis of an individual cloud document.
- [x] **ANALYZE-02**: User can request analysis of selected cloud files or folders.
- [x] **ANALYZE-03**: User can request analysis of an entire cloud connection after reviewing a file-count and byte-size estimate.
- [x] **ANALYZE-04**: User can monitor aggregate and per-item analysis progress through queued, downloading, extracting, classifying, indexed, and failed states.
- [x] **ANALYZE-05**: User can cancel queued analysis work and retry failed cloud documents.
- [x] **ANALYZE-06**: DocuVault does not repeat analysis when the provider item version or etag has not changed.
- [x] **ANALYZE-07**: Analyzing a cloud document never moves, renames, or rewrites the provider-owned file.
### Smart Search
- [ ] **SEARCH-01**: User can search local documents and analyzed cloud documents through one search experience.
- [ ] **SEARCH-02**: User can find documents using keywords or sentences matched against extracted text.
- [ ] **SEARCH-03**: User can find documents using semantic concepts or ideas rather than exact wording.
- [ ] **SEARCH-04**: Search results identify local/cloud source, provider, location, topics, and analysis status.
- [ ] **SEARCH-05**: User can filter search results by source, provider, folder, topic, and analysis status.
- [ ] **SEARCH-06**: Opening a cloud search result hydrates provider bytes only when preview or download requires them.
- [ ] **SEARCH-07**: Executing a search query never downloads cloud file bytes.
### Cache and Storage Minimization
- [x] **CACHE-01**: Provider-owned file bytes remain the source of truth unless the user explicitly imports a file into local DocuVault storage.
- [x] **CACHE-02**: DocuVault persists cloud metadata, extracted text, topics, and semantic search data independently of cached file bytes.
- [x] **CACHE-03**: DocuVault caches cloud file bytes only when required for opening, preview, or analysis.
- [x] **CACHE-04**: Configurable cache limits and safe eviction minimize local storage use without interrupting active work.
- [x] **CACHE-05**: Cached cloud content is isolated by user and connection and is never served without an ownership check.
### Change Tracking
- [x] **SYNC-01**: DocuVault records provider item identifiers, parent/location, version or etag, size, and modification time for indexed cloud items.
- [ ] **SYNC-02**: DocuVault marks analyzed cloud items stale when their provider version changes.
- [ ] **SYNC-03**: Files deleted outside DocuVault are removed from cloud navigation and excluded from search results after refresh.
- [ ] **SYNC-04**: Provider refresh jobs are idempotent and retry transient failures with bounded exponential backoff.
## Future Requirements
### Extended Cloud Mobility
- **XFER-01**: User can copy or move files between different cloud providers.
- **IMPORT-01**: User can permanently pin or import a cloud file into DocuVault-owned local storage.
- **OFFLINE-01**: User can mark folders for persistent offline availability.
### Sync Clients
- **CLIENT-01**: User can install a native desktop client for operating-system file integration.
- **CLIENT-02**: Native clients can synchronize selected DocuVault and cloud folders.
## Out of Scope
| Feature | Reason |
|---------|--------|
| Cross-provider move/copy | Requires transfer orchestration and conflict semantics beyond the virtual-local single-provider milestone |
| Native desktop sync client | v0.3 remains a responsive web application |
| Whole-drive offline mirror | Conflicts with the milestone's local-storage minimization goal |
| Real-time collaborative editing | Document management and discovery are the current focus |
| Automatic whole-cloud analysis without consent | Could create unexpected AI cost, provider load, and privacy impact |
| Permanent local pinning/import | Temporary bounded caching is sufficient for v0.3; explicit import remains future scope |
| Public unauthenticated links | Existing v0.x privacy boundary remains unchanged |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| CONN-01 | Phase 13 | Complete |
| CONN-02 | Phase 13 | Complete |
| CONN-03 | Phase 13 | Complete |
| CONN-04 | Phase 12 | Complete |
| CLOUD-01 | Phase 12 | Complete |
| CLOUD-02 | Phase 13 | Complete |
| CLOUD-03 | Phase 13 | Complete |
| CLOUD-04 | Phase 13 | Complete |
| CLOUD-05 | Phase 13 | Complete |
| CLOUD-06 | Phase 13 | Complete |
| CLOUD-07 | Phase 13 | Complete |
| CLOUD-08 | Phase 12 | Complete |
| CLOUD-09 | Phase 13 | Complete |
| ANALYZE-01 | Phase 14 | Complete |
| ANALYZE-02 | Phase 14 | Complete |
| ANALYZE-03 | Phase 14 | Complete |
| ANALYZE-04 | Phase 14 | Complete |
| ANALYZE-05 | Phase 14 | Complete |
| ANALYZE-06 | Phase 14 | Complete |
| ANALYZE-07 | Phase 14 | Complete |
| SEARCH-01 | Phase 15 | Pending |
| SEARCH-02 | Phase 15 | Pending |
| SEARCH-03 | Phase 15 | Pending |
| SEARCH-04 | Phase 15 | Pending |
| SEARCH-05 | Phase 15 | Pending |
| SEARCH-06 | Phase 15 | Pending |
| SEARCH-07 | Phase 15 | Pending |
| CACHE-01 | Phase 12 | Complete |
| CACHE-02 | Phase 12 | Complete |
| CACHE-03 | Phase 14 | Complete |
| CACHE-04 | Phase 14 | Complete |
| CACHE-05 | Phase 14 | Complete |
| SYNC-01 | Phase 12 | Complete |
| SYNC-02 | Phase 16 | Pending |
| SYNC-03 | Phase 16 | Pending |
| SYNC-04 | Phase 16 | Pending |
**Coverage:**
- v0.3 requirements: 36 total
- Mapped to phases: 36
- Unmapped: 0
---
*Requirements defined: 2026-06-17*
*Last updated: 2026-06-17 after roadmap creation*
.planning/ROADMAP.md
+157 -543
View File
@@ -1,561 +1,175 @@
# DocuVault — v1 Roadmap
# DocuVault Roadmap: v0.3 Reimagining Cloud Storage integration
_Last updated: 2026-06-02_
**Status:** Proposed
**Phases:** 12-16
**Requirements:** 36
**Defined:** 2026-06-17
## Mandatory Cross-Cutting Gates (every phase)
## Milestone Goal
Before any phase is marked complete, all three gates must pass:
Make connected cloud storage behave like first-class DocuVault storage: users can navigate and manage provider-owned files as if they were local, selectively analyze them, and find them through unified keyword and semantic search while DocuVault minimizes locally cached file bytes.
1. **Test gate** — `pytest -v` passes with zero failures; every new function/endpoint has at least one test; all security invariant tests pass (wrong owner, admin block, token replay)
2. **Security gate** — Security agent runs `bandit -r backend/` (zero HIGH), `pip audit` (zero critical/high), `npm audit --audit-level=high` (zero high/critical); admin endpoints verified to never return `password_hash`, `credentials_enc`, or document content; no hardcoded secrets
3. **Bug fix rule** — Any bug fix during execution must: (a) target the root cause, (b) change ≤50 lines, (c) include a regression test — no workarounds permitted
## Mandatory Cross-Cutting Gates
---
Before any phase is marked complete:
## Phases
1. Backend and frontend test suites pass with zero failures; every new function, endpoint, store, and component has focused coverage.
2. Security gate verifies user/connection/item ownership, credential secrecy, SSRF defenses, metadata-only audit logs, cache isolation, and no admin document-content access.
3. Dependency audits report no high/critical vulnerabilities.
4. Provider integration tests cover supported capabilities and explicit unsupported behavior.
5. User-facing changes update `AGENTS.md`, relevant README sections, and application patch/minor versions according to project protocol.
- [x] **Phase 1: Infrastructure Foundation** — PostgreSQL + MinIO wired into Docker Compose; Alembic migrations running; existing app still works
- [x] **Phase 2: Users & Authentication** — Full auth flow end-to-end (register, login, TOTP, backup codes, password reset, sign-out-all) with admin panel for user management
- [x] **Phase 3: Document Migration & Multi-User Isolation** — All documents in PostgreSQL + MinIO; per-user isolation enforced; existing UI still works
- [x] **Phase 4: Folders, Sharing, Quotas & Document UX** — Full document management UX (folders, sharing, quota bar, PDF preview, search, audit log)
- [x] **Phase 5: Cloud Storage Backends** — Users can connect OneDrive, Google Drive, Nextcloud, or WebDAV as a personal storage backend
## Phase Summary
---
| Phase | Name | Goal | Requirements |
|------:|------|------|--------------|
| 12 | 6/6 | Complete | 2026-06-21 |
| 13 | 11/11 | Complete | 2026-06-23 |
| 14 | 9/9 | Complete | 2026-06-23 |
| 15 | Unified Smart Search | Search local and analyzed cloud documents by exact text or semantic ideas without downloading files during queries | SEARCH-01..07 |
| 16 | Change Tracking and Reliability | Detect external provider changes, mark stale indexes, remove deleted items, and harden refresh behavior | SYNC-02..04 |
## Phase Details
### Phase 1: Infrastructure Foundation
### Phase 12: Cloud Resource Foundation
**Goal**: PostgreSQL + MinIO are wired into Docker Compose with a complete Alembic-managed schema; all services boot cleanly and the existing single-user document scanner continues to work exactly as before — no user-facing behavior change.
**Mode:** mvp
**Depends on**: Nothing (first phase)
**Requirements**: STORE-01, STORE-02, STORE-07
**Goal:** DocuVault has a provider-neutral cloud file capability contract and durable per-user cloud item index, and the shared browser can render cloud resources and supported actions without copying full provider files into local storage.
**Success Criteria** (what must be TRUE):
**Depends on:** Phase 11
**Requirements:** CONN-04, CLOUD-01, CLOUD-08, CACHE-01, CACHE-02, SYNC-01
1. `docker compose up` starts PostgreSQL, MinIO, and the FastAPI backend with no errors; health checks pass for all three services
2. Running `alembic upgrade head` applies the initial migration cleanly against the fresh PostgreSQL instance with no errors
3. The full existing document upload, text extraction, and AI classification workflow completes successfully — no regression in single-user behavior
4. MinIO object key schema `{user_id}/{document_id}/{uuid4()}{ext}` is enforced in the model layer; human-readable filenames are stored in the DB column, not in the MinIO key
**Success Criteria:**
**Plans**: 5 plans
1. Every supported provider reports normalized capabilities for browse, open, preview, upload, folder creation, rename, move, delete, and change tracking.
2. Browsing any connected provider persists normalized, owner-scoped cloud item metadata including provider ID/path, parent, type, size, modification time, and version/etag.
3. `StorageBrowser.vue` remains the single file browser and renders cloud actions from capabilities, including disabled actions with provider-specific explanations.
4. Provider-owned bytes remain outside DocuVault while metadata, extracted text placeholders, topic links, and semantic-index state can be persisted independently.
5. Ownership and admin-negative tests prove cloud connection and cloud item metadata cannot cross user boundaries.
- [x] 01-01-PLAN.md — Docker Compose service topology + Postgres init + Pydantic Settings + requirements
- [x] 01-02-PLAN.md — Wave 0 test scaffolds (xfail/skip stubs) + async pytest fixtures
- [x] 01-03-PLAN.md — SQLAlchemy ORM models + async engine + Alembic async migration (incl. alembic upgrade head)
- [x] 01-04-PLAN.md — StorageBackend ABC + MinIO backend + rewritten async services/storage.py
- [x] 01-05-PLAN.md — Lifespan + /health + API cutover + Celery worker + walking-skeleton e2e verify
### Phase 12.1: Fix Nextcloud root listing and sync visibility (INSERTED)
**Goal:** Restore visible, truthful, metadata-only cloud browsing by repairing Nextcloud's adapter contract, applying one completeness/freshness contract across all providers, and aligning the shared frontend browser with normalized provider identities.
**Requirements:** CONN-04, CLOUD-01, CACHE-01, SYNC-01
**Depends on:** Phase 12
**Plans:** 4/4 plans complete
**Execution waves:** Wave 1: 12.1-01; Wave 2: 12.1-02 after 01; Wave 3: 12.1-03 after 02; Wave 4: 12.1-04 after 01-03.
Plans:
- [x] 12.1-01-PLAN.md
- [x] 12.1-02-PLAN.md
- [x] 12.1-03-PLAN.md
- [x] 12.1-04-PLAN.md
- [x] 12.1-01 (Wave 1) — Restore the shared four-provider adapter contract, secure Nextcloud URL/redirect handling, and metadata-only listing behavior.
- [x] 12.1-02 (Wave 2; after 12.1-01) — Centralize complete/incomplete reconciliation so incomplete provider results cannot become fresh or delete cached metadata.
- [x] 12.1-03 (Wave 3; after 12.1-02) — Align the shared browser and trees with `kind`, opaque `provider_item_id` routing, lineage-based breadcrumbs, and server freshness.
- [ ] 12.1-04 (Wave 4; after 12.1-01 through 12.1-03) — Run sanitized two-mode live Nextcloud acceptance, rendered/security/secret gates, and phase closeout.
**Success Criteria:**
1. Nextcloud and generic WebDAV expose one canonical `CloudResourceAdapter.list_folder` implementation, and all four providers pass the same runtime identity/completeness/no-byte/no-mutation contract with provider-specific pagination fixtures.
2. Every outbound Nextcloud/WebDAV target, including redirects, is rejected unless each hop is HTTPS, same-origin, and passes URL plus resolved-address SSRF validation; automatic redirects are disabled.
3. `complete=False` never marks a folder fresh, advances `last_refreshed_at`, or authorizes unseen-item deletion in synchronous or worker paths; cached rows remain usable with a controlled warning.
4. The frontend classifies by `kind`, navigates through named routes/query serialization with opaque `provider_item_id` values, builds breadcrumbs from explicit navigation lineage rather than splitting provider IDs, and renders backend freshness verbatim.
5. Live Nextcloud validation first runs a nonblocking sanitized diagnostic; exact names/kinds become a blocking gate only after the owner-confirmed manifest is stored in a tracked, non-secret fixture. Unexpected live names are never printed or persisted.
6. Automated backend/frontend/rendered-flow tests, dedicated per-plan security reviews, dependency audits, an executable secret scan, documentation/version updates, and one atomic commit/push per plan pass without exposing credentials or provider bytes.
### Phase 13: Virtual-Local Cloud Operations
**Goal:** Users can maintain healthy cloud connections and perform the main file-management workflows in connected storage with the same shared browser interactions used for local files.
**Depends on:** Phase 12
**Requirements:** CONN-01, CONN-02, CONN-03, CLOUD-02, CLOUD-03, CLOUD-04, CLOUD-05, CLOUD-06, CLOUD-07, CLOUD-09
**Plans:** 11/11 plans complete
**Execution waves:** Wave 0: 13-01 and 13-02 in parallel; Wave 1: 13-03 after 13-01; Wave 2: 13-04 after 13-01 and 13-03; Wave 3: 13-05 after 13-01, 13-03, and 13-04; Wave 4: 13-06 after 13-05; Wave 5: 13-07 and 13-08 in parallel (13-07 after 13-02, 13-04, and 13-06; 13-08 after 13-03, 13-04, and 13-06); Wave 6: 13-09 after 13-08; Wave 7: 13-10 after 13-02, 13-04, 13-07, and 13-09; Wave 8: 13-11 after 13-03 through 13-10.
Plans:
- [x] 13-01-PLAN.md — Create red backend and provider-contract suites for reconnect, content, mutations, and audit secrecy.
- [x] 13-02-PLAN.md — Create red frontend/store suites for queue, preview, health UX, broader Drive consent, and no-probe-on-navigation.
- [x] 13-03-PLAN.md — Build the mutable cloud contract and orchestration seam without breaking centralized reconciliation.
- [x] 13-04-PLAN.md — Implement connection-ID reconnect, explicit health test, broader Drive scope handling, and authorized content routes.
- [x] 13-05-PLAN.md — Implement backend upload provider mechanics, typed route results, and refreshed-credential handoff.
- [x] 13-06-PLAN.md — Complete upload reconcile, freshness, and metadata-only audit follow-through before frontend queue wiring.
- [x] 13-07-PLAN.md — Wire the shared browser queue and binary-only preview or download fallback through thin cloud view handlers.
- [x] 13-08-PLAN.md — Implement backend create-folder and rename semantics with collision, stale, and stable-identity safeguards.
- [x] 13-09-PLAN.md — Implement backend move and delete semantics with same-connection, disclosure, security, and audit safeguards.
- [x] 13-10-PLAN.md — Finish shared-browser mutation UX, store-backed health behavior, reconnect copy, and the no-probe invariant.
- [x] 13-11-PLAN.md — Run closeout-only docs, versions, full gates, explicit secret scan, and ship-readiness checks.
**Success Criteria:**
1. Users can connect, test, reconnect, and disconnect providers while seeing current health and actionable reauthentication/error states.
2. Users can open or preview supported cloud documents and upload files into the current cloud folder through authorized DocuVault endpoints.
3. Users can create folders, rename items, move items within one connection, and delete items after confirmation wherever the provider supports each action.
4. Successful mutations immediately invalidate affected listings/index entries, refresh the shared browser, and write metadata-only audit events.
5. Provider-specific tests verify operation semantics, conflict/error responses, token refresh persistence, SSRF protection, and explicit unsupported capabilities.
### Phase 14: Selective Analysis and Byte Cache
**Goal:** Users can analyze individual files, selected scopes, or whole connections through observable and controllable background jobs, while file bytes are hydrated only on demand and evicted safely.
**Depends on:** Phase 13
**Requirements:** ANALYZE-01, ANALYZE-02, ANALYZE-03, ANALYZE-04, ANALYZE-05, ANALYZE-06, ANALYZE-07, CACHE-03, CACHE-04, CACHE-05
**Plans:** 9/9 plans complete
**Execution waves:** Wave 0: 14-01; Wave 1: 14-02 after 14-01; Wave 2: 14-03 after 14-02; Wave 3: 14-04 after 14-02 and 14-03; Wave 4: 14-05 after 14-03 and 14-04; Wave 5: 14-06 after 14-03 and 14-05; Wave 6: 14-07 after 14-04 and 14-05; Wave 7: 14-08 after 14-03 and 14-07; Wave 8: 14-09 after 14-01 through 14-08.
Plans:
- [x] 14-01-PLAN.md — Create red backend/frontend tests for analysis scopes, estimates, cache invariants, queue states, and security negatives.
- [x] 14-02-PLAN.md — Add durable cache/job/settings schema plus version-key and settings helpers.
- [x] 14-03-PLAN.md — Implement owner-scoped byte cache service, quota accounting, pinning, eviction, and cache settings/status API.
- [x] 14-04-PLAN.md — Implement estimate/enqueue/status/cancel/skip/retry analysis APIs with idempotent job creation.
- [x] 14-05-PLAN.md — Implement Celery-backed cloud analysis processing, cache hydration, extraction, classification, and cancellation.
- [x] 14-06-PLAN.md — Route existing cloud open/preview/download byte hydration through the bounded cache lifecycle.
- [x] 14-07-PLAN.md — Wire shared-browser analysis actions, estimates, aggregate progress, expandable queue, and controls.
- [x] 14-08-PLAN.md — Add Settings controls for cache limit, progress detail, and failure behavior.
- [x] 14-09-PLAN.md — Run closeout docs, versions, full test/security gates, validation, commit, and push.
**Success Criteria:**
1. Users can analyze one file, a multi-selection, a folder tree, or a whole connection after reviewing recursive file-count and byte-size estimates.
2. The UI exposes aggregate and per-item queued, downloading, extracting, classifying, indexed, cancelled, and failed states with retry and queued-work cancellation.
3. Analysis jobs are idempotent by cloud item and provider version/etag, and they never mutate the provider-owned file.
4. Cloud bytes are cached only for active opening, preview, or analysis work and are evicted by configurable limits without interrupting pinned active jobs.
5. Cache ownership, cache-key versioning, cancellation, duplicate-job, failure-retry, and eviction behavior have dedicated tests.
### Phase 15: Unified Smart Search
**Goal:** One search experience finds local and analyzed cloud documents by keywords, sentences, or semantic ideas and opens cloud results through on-demand hydration.
**Depends on:** Phase 14
**Requirements:** SEARCH-01, SEARCH-02, SEARCH-03, SEARCH-04, SEARCH-05, SEARCH-06, SEARCH-07
**Success Criteria:**
1. A single query returns authorized local and analyzed cloud results ranked through full-text and semantic relevance.
2. Keyword and sentence searches match persisted extracted text, while idea searches use persisted embeddings or equivalent semantic indexes.
3. Results clearly show source, provider, cloud location, topics, and current analysis/stale status and can be filtered by those fields.
4. Search execution performs no provider file download; only opening or previewing a result may hydrate bytes.
5. Search isolation, ranking, filtering, stale-result handling, and no-download-on-query invariants have automated coverage.
### Phase 16: Change Tracking and Reliability
**Goal:** DocuVault remains accurate when users or other applications modify connected cloud storage outside DocuVault.
**Depends on:** Phase 15
**Requirements:** SYNC-02, SYNC-03, SYNC-04
**Success Criteria:**
1. Provider delta feeds or bounded metadata refreshes detect changed versions and mark previously analyzed items stale until reanalysis.
2. Items deleted outside DocuVault disappear from navigation and are excluded from search without deleting unrelated user data.
3. Refresh jobs are idempotent, cursor-aware where supported, rate-limited, and retry transient failures with bounded exponential backoff.
4. Users can see refresh/stale/error state and deliberately reanalyze changed items.
5. End-to-end UAT verifies cloud-as-local operations, selective analysis, cache offload, unified smart search, and external-change recovery across supported provider classes.
## Coverage
- v0.3 requirements: 36
- Mapped to phases: 36
- Unmapped: 0
- Duplicate mappings: 0
---
### Phase 2: Users & Authentication
**Goal**: Users can register, log in (with optional TOTP 2FA), reset their password, and sign out all active sessions; admins can manage user accounts and assign AI providers — all enforced by a complete FastAPI dependency chain.
**Mode:** mvp
**Depends on**: Phase 1
**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05, AUTH-06, AUTH-07, AUTH-08, SEC-01, SEC-02, SEC-03, SEC-05, SEC-06, SEC-07, ADMIN-01, ADMIN-02, ADMIN-03, ADMIN-04, ADMIN-05, ADMIN-07
**Success Criteria** (what must be TRUE):
1. A new user can register with an email and password that passes strength validation; a password from the HaveIBeenPwned list is rejected with a clear error
2. A logged-in user can enroll a TOTP authenticator app, receive 8–10 backup codes, explicitly acknowledge them, and thereafter be required to supply a TOTP code (or backup code) on every login — a backup code is invalidated on first use
3. A user who forgets their password can receive a reset email, follow the link within 1 hour, set a new password, and is then returned to the TOTP login gate (not auto-logged in)
4. A user can trigger "sign out all devices" from account settings; all other active sessions are immediately invalidated and any reuse of a rotated refresh token revokes the entire token family
5. An admin user can create, deactivate, and reset a user account, and assign an AI provider and model to that user; admin API endpoints never return document content or credentials_enc (per-user document auth enforcement deferred to Phase 3 per D-07)
**Plans**: 5 plans
**Wave 1** — Foundation
- [x] 02-01-PLAN.md — Auth service layer (Argon2, JWT, refresh tokens, TOTP, backup codes, HIBP, security alert), FastAPI deps, BackupCode model + password_must_change migration
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 02-02-PLAN.md — Register/login (TOTP + backup code paths) + refresh/logout/change-password endpoints + CSP/Origin validation/rate-limit (IP + per-account) + Vue auth store + router guard + Login/Register views
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 02-03-PLAN.md — TOTP enrollment + backup codes + password reset + sign-out-all endpoints + AccountView + TotpEnrollment + BackupCodesDisplay + PasswordReset views
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 02-04-PLAN.md — Admin backend: user CRUD, quota, AI config endpoints with get_current_admin enforced + tests
**Wave 5** *(blocked on Wave 4 completion)*
- [x] 02-05-PLAN.md — Admin panel frontend: AdminView + three tab components + AppSidebar admin link and user identity footer
**Cross-cutting constraints:**
- JWT access token in Pinia memory only — never localStorage (Plans 02, 03, 05)
- Refresh token httpOnly SameSite=Strict cookie on all token issuance (Plans 02, 03)
- Admin endpoints never return document content or credentials_enc (Plans 04, 05)
- All auth endpoints rate-limited per-IP and per-account (Plans 02, 03)
**UI hint**: yes
---
### Phase 3: Document Migration & Multi-User Isolation
**Goal**: All existing documents have been migrated from flat-file JSON + filesystem into PostgreSQL + MinIO; all new uploads use the presigned URL flow; per-user isolation is enforced at the DB level; the existing document UI works without regression; the backend is stateless and ready for horizontal scaling.
**Mode:** mvp
**Depends on**: Phase 2
**Requirements**: STORE-03, STORE-04, STORE-05, STORE-06, STORE-08, SEC-04, DOC-03, DOC-04, DOC-05
**Success Criteria** (what must be TRUE):
1. Every document present before migration is accessible after migration with the same metadata and extracted text; a count reconciliation check confirms zero document loss
2. Two concurrent uploads that would together exceed a user's 100 MB quota result in exactly one success and one 413 rejection — the quota never goes over limit
3. A document delete atomically decrements the user's recorded quota usage; after deletion the quota reflects the freed bytes
4. Requesting a document object key or presigned URL for a document owned by a different user returns 403 — no cross-user object access is possible through any request parameter manipulation; all /api/documents/* endpoints enforce get_current_user and return 403 when the requesting user's role is admin (completing SC5 from Phase 2)
5. AI classification for each document uses the provider and model assigned to that user by the admin, not any user-supplied or default value
**Plans**: 5 plans
**Wave 1** — Migration + test scaffolds
- [x] 03-01-PLAN.md — Wave 0 test scaffolds (auth_user/admin_user/MinIO mock fixtures + 19 xfail stubs) + Alembic migration 0003 (null-user cleanup, NOT NULL constraint, topic cleanup, quota reconciliation, ix_topics_user_id) — Complete 2026-05-23
**Wave 2** *(blocked on Wave 1)*
- [ ] 03-02-PLAN.md — Presigned upload backend: StorageBackend ABC + MinIOBackend dual client + generate_presigned_put_url/stat_object + /api/documents/upload-url + /api/documents/{id}/confirm with atomic quota UPDATE + GET /api/auth/me/quota + delete-with-quota + abandoned-upload Celery beat + docker-compose CORS/celery-beat
**Wave 3** *(blocked on Wave 2)*
- [x] 03-03-PLAN.md — Auth guards: get_regular_user dep + ownership assertions on every /api/documents/* handler (404 not 403) + admin 403 + real user_id in object_key + namespace-scoped /api/topics/* + POST /api/admin/topics + classifier topic-namespace plumbing
**Wave 4** *(blocked on Wave 3)*
- [x] 03-04-PLAN.md — Settings retirement + per-user AI: delete /api/settings + remove load_settings/save_settings + classifier accepts ai_provider/ai_model kwargs + Celery task resolves user.ai_provider via DB + frontend SettingsView placeholder + remove settings store/API — Complete 2026-05-23
**Wave 5** *(blocked on Wave 4)*
- [ ] 03-05-PLAN.md — Frontend upload flow + quota bar: 3-step upload action with XHR progress + UploadProgress.vue progress bar and quota rejection error block + QuotaBar.vue + AppSidebar embed + quota state in auth store + human checkpoint
**Cross-cutting constraints:**
- Atomic quota UPDATE pattern only lives in Plan 02; never duplicate (CLAUDE.md)
- Every /api/documents/* handler injects get_regular_user (Plan 03)
- AI provider/model resolved only via Celery task DB lookup (Plan 04)
- Browser XHR PUT to MinIO sends NO Authorization header (Plan 05)
**Phase gates (must pass before Phase 3 is complete):**
- [ ] `pytest -v` — zero failures; presigned URL, quota enforcement, ownership isolation, and admin-403 all covered
- [ ] Security agent: path traversal check on object key construction; cross-user IDOR tests; quota race condition test
- [ ] Bandit + pip audit + npm audit all clean
**UI hint**: yes
---
### Phase 4: Folders, Sharing, Quotas & Document UX
**Goal**: Users have a complete document management experience — organized with folders, shared by handle, warned before they hit quota, able to preview PDFs in-browser, and served by a searchable document list; admins can view the append-only audit log.
**Mode:** mvp
**Depends on**: Phase 3
**Requirements**: FOLD-01, FOLD-02, FOLD-03, FOLD-04, FOLD-05, SHARE-01, SHARE-02, SHARE-03, SHARE-04, SHARE-05, SEC-08, SEC-09, ADMIN-06, DOC-01, DOC-02
**Success Criteria** (what must be TRUE):
1. A user can create, rename, and delete folders; moving a document between folders preserves its metadata and AI classification; deleting a non-empty folder prompts with the content count before proceeding
2. A user can share a document with another user by handle; the recipient sees it appear in a "Shared with me" virtual folder with no storage quota charged against them; the owner can revoke access and the shared entry disappears immediately for the recipient
3. The sidebar quota bar displays current usage in MB; it turns amber at 80% and red at 95%; an upload that would exceed the limit is rejected with an error showing current usage, the rejected file size, and a link to storage settings
4. Any document in the user's library can be previewed in-browser as a PDF; document bytes are proxied through the app and no presigned URLs are exposed to the browser (native browser PDF rendering via Content-Type header)
5. An admin can view the audit log filtered by date range, user, and action type; the log contains no document content, filenames, or extracted text; account deletion triggers cleanup of all user files before DB records are removed
**Plans**: 9 plans
**Wave 1** — Test scaffolds + DB migration (parallel)
- [x] 04-01-PLAN.md — Wave 0 test stubs: test_folders.py + test_shares.py + test_audit.py + proxy stubs in test_documents.py + SEC-08/SEC-09 stubs in test_security.py
- [x] 04-02-PLAN.md — Alembic migration 0004 (users.pdf_open_mode, GIN FTS index, audit-logs bucket) + MinIOBackend.put_object_raw()
**Wave 2** *(blocked on Wave 1)*
- [x] 04-03-PLAN.md — Audit service (write_audit_log) + Folders API (FOLD-01..05): POST/GET/PATCH/DELETE /api/folders + PATCH /api/documents/{id}/folder + document list sort/search/is_shared extension
- [ ] 04-04-PLAN.md — Shares API (SHARE-01..05): POST/GET /api/shares + GET /api/shares/received + DELETE /api/shares/{id} with IDOR protection
**Wave 3** *(blocked on Wave 2)*
- [ ] 04-05-PLAN.md — PDF streaming proxy GET /api/documents/{id}/content with Range header support + PATCH /api/auth/me/preferences (pdf_open_mode)
- [ ] 04-06-PLAN.md — Admin audit log API (GET /api/admin/audit-log, CSV export) + Celery beat daily audit export task + celery_app.py beat schedule
**Wave 4** *(blocked on Wave 3)*
- [ ] 04-07-PLAN.md — SEC-08/SEC-09 hardening + audit log backfill into auth.py/admin.py/documents.py + CloudConnectionOut Pydantic model + delete-user file cleanup
**Wave 5** *(blocked on Wave 4)*
- [ ] 04-08-PLAN.md — Frontend data layer: API client functions + useFoldersStore + documents store extension + Vue Router routes (/folders/:folderId, /shared)
**Wave 6** *(blocked on Wave 5)*
- [ ] 04-09-PLAN.md — Frontend UI: all new components (FolderRow, FolderBreadcrumb, FolderDeleteModal, ShareModal, DocumentPreviewModal, SearchBar, SortControls, AuditLogTab) + view wiring (AppSidebar, DocumentCard, HomeView, FolderView, SharedView, SettingsView, AdminView) + human checkpoint
**Phase gates (must pass before Phase 4 is complete):**
- [ ] `pytest -v` — zero failures; folder ownership, share revocation, quota bar, PDF proxy (no presigned URL exposure) all covered
- [ ] Security agent: audit log verified to contain zero document content; sharing IDOR tests; PDF proxy verified to not leak presigned URLs or object keys
- [ ] Bandit + pip audit + npm audit all clean
**UI hint**: yes
---
### Phase 5: Cloud Storage Backends
**Goal**: Users can connect OneDrive, Google Drive, Nextcloud, or a generic WebDAV server as a personal storage backend; credentials are encrypted with a per-user HKDF-derived key; connection status is visible; local and cloud storage coexist; the `StorageBackend` ABC makes adding further backends straightforward.
**Mode:** mvp
**Depends on**: Phase 4
**Requirements**: CLOUD-01, CLOUD-02, CLOUD-03, CLOUD-04, CLOUD-05, CLOUD-06, CLOUD-07
**Success Criteria** (what must be TRUE):
1. A user can connect OneDrive, Google Drive, Nextcloud, or a WebDAV endpoint through an OAuth or credential flow; the connection status is displayed as `ACTIVE`, `REQUIRES_REAUTH`, or `ERROR` — never shows raw credentials
2. When an OAuth token is revoked externally (simulated `invalid_grant` response), the connection status transitions to `REQUIRES_REAUTH` without a 500 error; the user is shown a re-authentication prompt
3. A user can select their connected cloud backend as the default storage destination for new uploads; local MinIO storage remains available as an alternative; existing local documents are unaffected
4. A user can disconnect a cloud backend; credentials are permanently deleted from the DB and a subsequent attempt to use that backend returns an appropriate error — no orphaned data remains
5. An admin API response for a user's cloud connections returns only `provider, display_name, connected_at, status` — the `credentials_enc` column is never present in any serialized response
**Plans**: 12 plans (8 original + 3 UAT gap closure + 1 gap closure wave)
**Wave 1** — Test scaffold + dependencies
- [x] 05-01-PLAN.md — Wave 0 xfail stubs, conftest cloud fixtures, requirements.txt packages, config.py settings
**Wave 2** — Shared utilities
- [x] 05-02-PLAN.md — cloud_utils.py (SSRF + HKDF), cloud_cache.py (TTLCache), storage factory extension
**Wave 3** — Cloud backends (parallel, both blocked on Wave 2 / Plan 05-02)
- [x] 05-03-PLAN.md — GoogleDriveBackend + OneDriveBackend (all 7 StorageBackend methods)
- [x] 05-04-PLAN.md — NextcloudBackend + WebDAVBackend (all 7 StorageBackend methods)
**Wave 4** — Cloud API
- [x] 05-05-PLAN.md — All /api/cloud/* endpoints + /api/users/me/default-storage + main.py router registration
**Wave 5** — Document routing + full test suite
- [x] 05-06-PLAN.md — Upload/content proxy cloud routing + all 15 tests promoted to passing
**Wave 6** — Frontend settings UI
- [x] 05-07-PLAN.md — cloudConnections store + API client + SettingsView 3-tab + SettingsCloudTab + CloudCredentialModal
**Wave 7** — Frontend sidebar (human checkpoint)
- [x] 05-08-PLAN.md — AppSidebar cloud section + CloudProviderTreeItem + CloudFolderTreeItem + human checkpoint
**Wave 8** — UAT gap closure (parallel, all independent)
- [x] 05-09-PLAN.md — Cloud document open/re-analyze/edit: authenticated fetch+Blob URL, cloud-aware Celery task, PATCH /api/documents/{id}
- [x] 05-10-PLAN.md — OAuth initiate fix (JSON response), Nextcloud custom endpoint edit round-trip, Edit button on ERROR rows, confirmation text overflow
- [x] 05-11-PLAN.md — Admin hard-delete with password confirmation: UserDeleteConfirm backend model + inline frontend panel
**Wave 9** — Post-UAT gap closure
- [x] 05-12-PLAN.md — OAuth 400 preflight (unconfigured creds), 502 cloud fallback, upload hint in CloudStorageView, celery-worker volume mount
**Phase gates (must pass before Phase 5 is complete):**
- [x] `pytest -v` — zero failures; SSRF prevention on WebDAV/Nextcloud user-supplied URLs; credential encryption/decryption round-trip; admin response never exposes `credentials_enc`; OAuth invalid_grant handling
- [x] Security agent: SSRF allowlist verification; credential key derivation correctness; connection status never leaks raw credential values
- [x] Bandit + pip audit + npm audit all clean
- [x] UAT gaps resolved and re-tested (05-09, 05-10, 05-11, 05-12)
**UI hint**: yes
---
### Phase 6: Performance & Production Hardening
**Goal**: The application is ready for production deployment — observable, load-tested, and hardened; response times meet SLA targets under concurrent load; all auth and document endpoints are rate-limited; structured logging and distributed tracing are in place; the Docker image runs as a non-root user with a read-only filesystem.
**Mode:** mvp
**Depends on**: Phase 5
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. All API endpoints respond within defined latency targets (p50/p95/p99) under a realistic load test (e.g., 50 concurrent users, 5-minute soak)
2. Structured JSON logging (correlation IDs, user ID, request latency) is emitted to stdout; a local log aggregation stack (Loki or similar) captures and queries them
3. All auth endpoints (login, register, password reset, TOTP) enforce per-IP and per-account rate limits that cannot be bypassed by header manipulation
4. Container hardening is complete: non-root user, read-only root filesystem, dropped Linux capabilities; `docker scout` or equivalent reports zero critical CVEs
5. A runbook documents all environment variables, startup/shutdown procedures, backup strategy, and on-call escalation path; the app can be stood up from scratch using only the runbook
**Plans**: 6 plans (4 waves)
**Wave 0** — Test scaffolds + package verification
- [x] 06-01-PLAN.md — Nyquist Wave 0: xfail stubs (test_logging.py, test_rate_limiting.py), Locust skeleton, package legitimacy checkpoint (D-01, D-04, D-11, D-12)
**Wave 1** *(blocked on Wave 0 completion)*
- [x] 06-02-PLAN.md — structlog JSON logging + CorrelationIDMiddleware + Loki/Promtail/Grafana Docker Compose stack (D-01, D-02, D-03)
- [x] 06-03-PLAN.md — Locust locustfile.py with JWT auth + SLA gate listener (D-04, D-05, D-06)
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 06-04-PLAN.md — Multi-stage Dockerfile + read_only/tmpfs/cap_drop on backend + celery-worker (D-07, D-08, D-09)
- [x] 06-05-PLAN.md — Trusted-proxy get_client_ip body + per-account rate limiter on document/cloud endpoints (D-11, D-12, D-13)
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 06-06-PLAN.md — docker scout CVE gate + RUNBOOK.md (D-10, D-14)
**Cross-cutting constraints:**
- get_client_ip lives ONLY in backend/deps/utils.py — replace body in-place, no new function (Plans 05)
- celery-beat intentionally excluded from read_only: true (Plan 04)
- locust must NOT be in requirements.txt — use requirements-dev.txt (Plan 03)
- CorrelationIDMiddleware registered LAST in main.py — Starlette reverse order (Plan 02)
---
### Phase 6.1: Close v1.0 audit gaps: SHARE-02/STORE-06/ADMIN-06
**Goal**: Close three v1.0 requirements that remain unimplemented — atomic quota decrement on document delete (STORE-06), "Shared with me" virtual folder without recipient quota charge (SHARE-02), and admin audit log viewer with date/user/action type filters (ADMIN-06).
**Mode:** mvp
**Depends on**: Phase 6
**Requirements**: STORE-06, SHARE-02, ADMIN-06
**Success Criteria** (what must be TRUE):
1. Deleting a document atomically decrements the owning user's quota; after deletion the quota reflects the freed bytes with no race condition under concurrent deletes
2. A user who receives a shared document sees it appear in a "Shared with me" virtual folder; the recipient's quota usage is not charged for the shared document's storage
3. An admin can view the audit log filtered independently by date range, user, and action type; filtered results contain no document content, filenames, or extracted text
**Plans**: 2 plans
**Wave 1** — Test promotion (parallel)
- [x] 06.1-01-PLAN.md — Promote test_shares.py stubs to real tests + second_auth_user fixture (SHARE-01..05)
- [x] 06.1-02-PLAN.md — Promote test_audit.py stubs to real tests (ADMIN-06)
**Phase gates (must pass before Phase 6.1 is complete):**
- [ ] `pytest -v` — zero failures; all 7 share tests + 4 audit log tests passing
- [ ] Security agent: bandit + pip audit + npm audit all clean
- [ ] STORE-06 confirmed: `test_delete_decrements_quota` passes under `INTEGRATION=1`
---
### Phase 6.2: Close v1 sharing + cloud-delete + CSV export gaps
**Goal**: Close remaining v1 gaps — sharing edge cases (SHARE-03/SHARE-05), cloud document deletion propagation to the remote backend, and CSV export + daily export UI for the admin audit log (ADMIN-06).
**Mode:** mvp
**Depends on**: Phase 6.1
**Requirements**: SHARE-03, SHARE-05, ADMIN-06
**Success Criteria** (what must be TRUE):
1. Documents shared with others display a "Shared" badge in the owner's list view (reads doc.is_shared, not doc.share_count)
2. Owner can set permission to "view" or "edit" when creating a share and toggle it per-recipient afterward; PATCH /api/shares/{id} enforces IDOR protection (404 on wrong owner)
3. Deleting a cloud document propagates the delete to the cloud provider; failure shows a warning modal with "Remove from app" fallback; ?remove_only=true removes only the DB record; cloud docs never affect quota on delete
4. Admin can download filtered audit log CSV via fetch+Blob (not window.location.href); audit log entries show user handles instead of raw UUIDs; user filter accepts handles (not UUIDs)
5. Admin can list and download Celery-generated daily audit export files from a new section in the Audit Log tab
**Plans**: 4 plans
**Wave 0** — Test stubs
- [x] 06.2-01-PLAN.md — 11 xfail stubs across test_shares.py, test_documents.py, test_audit.py
**Wave 1** — Feature slices (parallel)
- [x] 06.2-02-PLAN.md — SHARE-05 badge fix + SHARE-03 permission control (backend PATCH + frontend dropdown + toggle)
- [x] 06.2-03-PLAN.md — Cloud-delete propagation + structured error response + remove_only path + DocumentView warning modal
**Wave 2** — Audit log enrichment
- [x] 06.2-04-PLAN.md — Audit handle JOIN + user_handle filter + CSV fetch+Blob fix + daily-export list + download endpoints + AuditLogTab UI
**Phase gates (must pass before Phase 6.2 is complete):**
- [x] `pytest -v` — 344 passed, 1 pre-existing unrelated failure (test_extract_docx missing module)
- [x] Security agent: bandit + pip audit + npm audit all clean (SECURITY.md threats_open: 0)
- [x] IDOR on PATCH /api/shares/{id}: test_share_patch_idor passes
- [x] Date regex validation confirmed: GET /api/admin/audit-log/daily-exports/invalid-date returns 404
- [x] window.location.href removed from AuditLogTab.vue confirmed by grep
**Status: ✓ Complete (2026-06-01)**
### Phase 7: Redo and optimize LLM integration
**Goal:** A fully refactored, production-reliable AI provider layer: AI provider settings live in a new `system_settings` DB table (replacing env-only config), API keys encrypted at rest via HKDF/AES-GCM (same pattern as cloud credentials), all OpenAI-compatible providers (Groq, xAI, DeepSeek, OpenRouter, Gemini-compat, Mistral-compat, Ollama, LMStudio) handled by a single `GenericOpenAIProvider` class, Anthropic uses native `output_config.format.type="json_schema"` structured output, JSON-mode enforced everywhere with `parse_classification()` as fallback, Celery exponential-backoff retry (30s/90s/270s) replaces silent failure on classification errors, per-provider context window size with smart 60/40 truncation replaces the global `MAX_AI_CHARS`, the singleton `_client` pattern restores httpx connection-pool reuse, an admin AI Providers panel allows interactive configuration plus test-connection, and a "Re-analyze" button on the document card re-queues failed classifications.
**Mode:** standard
**Depends on:** Phase 6.2
**Requirements**: D-01..D-18 (CONTEXT.md decisions; no REQ-IDs yet mapped — phase introduces new infrastructure)
**Success Criteria** (what must be TRUE):
1. AI provider settings live in `system_settings`; admin can view, edit, and atomically activate any provider via `PUT /api/admin/ai-config`; `GET /api/admin/ai-config` never returns `api_key_enc` or any decrypted key value
2. A document whose classification raises an exception is automatically retried by Celery at 30 s, 90 s, and 270 s; after the third failure the document's status remains `classification_failed` and no further retries occur
3. All OpenAI-compatible providers route through `GenericOpenAIProvider`; classify/suggest pass `response_format={"type":"json_object"}` when `supports_json_mode` is True (Gemini preset is False and falls back to `parse_classification()`); Anthropic uses `output_config.format.type="json_schema"` with a constrained schema
4. `MAX_AI_CHARS` no longer exists in `openai_provider.py`, `anthropic_provider.py`, or `classifier.py`; each provider truncates input text using its own `context_chars` value via a 60% head + 40% tail strategy
5. A failed document shows a red "Classification failed" badge and a "Re-analyze" button on the document card; clicking the button calls `POST /api/documents/{id}/classify`, which sets the document to `processing` and re-queues the Celery task
**Plans**: 5 plans (5 waves)
**Wave 1** — Foundation: migration, ORM model, encryption helpers, Wave 0 test stubs
- [x] 07-01-PLAN.md — Alembic migration 0005 (system_settings table) + SystemSettings ORM model + services/ai_config.py (HKDF helpers + load_provider_config + env seed on startup) + Wave 0 xfail stubs for D-01..D-16 (test_ai_providers.py, test_ai_config.py, test_admin_ai_config.py, test_document_tasks.py)
**Wave 2** *(blocked on Wave 1)* — Provider layer: ProviderConfig, GenericOpenAIProvider, singleton client fix, registry
- [x] 07-02-PLAN.md — ProviderConfig Pydantic model + PROVIDER_DEFAULTS + SUPPORTS_JSON_MODE + GenericOpenAIProvider(OpenAIProvider) + OpenAIProvider singleton refactor + ollama/lmstudio context_chars + MAX_AI_CHARS removal from openai_provider.py + classifier.py + registry-based ai/__init__.py get_provider(config: ProviderConfig) + anthropic>=0.95.0 pin
**Wave 3** *(blocked on Wave 2)* — Anthropic + Classifier wiring
- [x] 07-03-PLAN.md — AnthropicProvider singleton + output_config json_schema + smart truncation + MAX_AI_CHARS removal + classifier.classify_document driven by load_provider_config (no inline _settings dict) + ai_config stub removed in favor of real ProviderConfig + load_provider_config_by_id helper
**Wave 4** *(blocked on Wave 3)* — Celery retry harness + Re-queue endpoint
- [x] 07-04-PLAN.md — Celery extract_and_classify decorator gains bind=True + max_retries=3 + _ClassificationError sentinel + 30/90/270 backoff + _mark_classification_failed on exhaustion + POST /api/documents/{id}/classify changes to re-queue Celery (sets status=processing, calls .delay()) — promotes test_retry_backoff, test_exhaustion_sets_failed_status, test_reclassify_requeues_celery
**Wave 5** *(blocked on Wave 4)* — Admin UI + Frontend badge
- [x] 07-05-PLAN.md — Admin AI-config backend (GET/PUT/test-connection with whitelist + audit logging + atomic is_active flip) + frontend API client helpers (getAiConfig/saveAiConfig/testAiConnection) + AdminAiConfigTab.vue global System AI Providers section ABOVE existing per-user table + DocumentCard.vue classification_failed badge + Re-analyze button + human checkpoint UAT
**Cross-cutting constraints:**
- `api_key_enc` is never returned by any admin endpoint — enforced by `_ai_config_to_dict()` whitelist (Plan 05)
- HKDF domain separation: AI settings use `info=b"ai-provider-settings"`, cloud credentials use `info=b"cloud-credentials"` (Plan 01)
- `is_active` flip is atomic: single `UPDATE SET is_active = (provider_id = $target)` — never read-then-write (Plan 05)
- Provider clients are stored as `self._client` in `__init__` — never recreated per call (Plans 02, 03)
- `MAX_AI_CHARS` removal must cover all three locations: openai_provider.py L5, anthropic_provider.py L5, classifier.py L28 (Plans 02 + 03)
- Celery `self.retry()` must be raised from the outer sync task body, never inside `asyncio.run()` (Plan 04 — Pitfall 3)
- `extra_hosts: ["host.docker.internal:host-gateway"]` already present in docker-compose.yml — D-14 is already done; no docker-compose changes required (RESEARCH.md)
- AdminAiConfigTab.vue per-user assignment table is preserved untouched; the new global system section is added ABOVE it (Plan 05 — Pitfall 6)
**Phase gates (must pass before Phase 7 is complete):**
- [x] `pytest -v` — zero failures; D-01/D-03/D-05/D-06/D-07/D-09/D-10/D-11/D-12/D-13/D-16 covered by promoted tests (347 passed, 1 pre-existing failure test_extract_docx missing module)
- [x] Security agent: bandit -r backend/ (zero HIGH), npm audit --audit-level=high (2 moderate esbuild/vite dev-only — no high/critical); pip-audit not runnable locally (Python 3.9 vs 3.12 requirements), inherited clean gate from Phase 6.2
- [x] `_ai_config_to_dict()` confirmed to never include `api_key_enc` (test_get_never_returns_key passes; whitelist at admin.py:62)
- [x] HKDF domain separation verified: test_encrypt_api_key_domain_isolation passes (test_ai_config.py:21)
- [x] Atomic `is_active` flip verified: test_set_active_provider_atomic passes (test_admin_ai_config.py:77)
- [x] Human checkpoint UAT approves admin panel + DocumentCard badge end-to-end (07-UAT.md: 11/11 passed 2026-06-05)
**UI hint**: yes
---
### Phase 7.1: Security: session revocation on privilege change (CR-01..03) (INSERTED)
**Goal**: Fix the three missing session-revocation calls in `backend/api/auth.py`: `change_password`, `enable_totp`, and `disable_totp` must all call `revoke_all_refresh_tokens()` (excluding the current session). Add `sessions_revoked` to their response shapes and a frontend toast when other sessions are terminated.
**Mode:** quick
**Depends on**: Phase 7
**Requirements**: CR-01, CR-02, CR-03
**Plans**: 2 plans
**Wave 1** — Backend: service + API changes
- [ ] 07.1-01-PLAN.md — Add skip_token_hash param to revoke_all_refresh_tokens + wire revoke into change_password, enable_totp, disable_totp with sessions_revoked response + audit log
**Wave 2** *(blocked on Wave 1)*
- [ ] 07.1-02-PLAN.md — Tests (3 new test_*_revokes_other_sessions) + frontend toast in SettingsAccountTab.vue + TotpEnrollment.vue
---
### Phase 7.2: Security — JTI Claim + Redis Access-Token Revocation (INSERTED)
**Goal**: Add a `jti` (JWT ID) claim to every issued access token. In `get_current_user`, check `redis.get("jti_revoked:{jti}")` and raise 401 if set. Add `revoke_access_token(jti, ttl)` helper called from `change_password`, `enable_totp`, `disable_totp`, and admin account deactivation. Closes the 15-minute window where a revoked session's live access token remains valid.
**Mode:** quick
**Depends on**: Phase 7.1
**Requirements**: Tracked in `.planning/codebase/CONCERNS.md` §"No JTI Claim and No JTI Revocation in Redis"
**Status:** Not planned yet
---
### Phase 7.3: Security — ES256 Algorithm Upgrade (INSERTED)
**Goal**: Replace HS256 with ES256 (ECDSA P-256) for JWT signing. Generate a P-256 key pair; store private key in `JWT_PRIVATE_KEY` env var, public key in `JWT_PUBLIC_KEY`. Update `create_access_token` and all `decode_*` functions. Rotate all active refresh tokens on first boot after deploy. A leaked public key cannot forge tokens.
**Mode:** quick
**Depends on**: Phase 7.2
**Requirements**: Tracked in `.planning/codebase/CONCERNS.md` §"JWT Algorithm Downgrade: HS256 Instead of ES256"
**Plans**: 3 plans
**Wave 0** — Test scaffolds (no production code)
- [x] 07.3-01-PLAN.md — Wave 0 xfail stubs: test_auth_es256.py (9 stubs covering ES256-01..05 + RM-01..03 + CFG-01 satellite) + extend test_settings_has_jwt_config for refresh_token_expire_hours
**Wave 1** *(blocked on Wave 0)* — ES256 core + startup rotation
- [x] 07.3-02-PLAN.md — config.py jwt_private_key/jwt_public_key/refresh_token_expire_hours + services/auth.py 4 sites to ES256 + main.py _rotate_tokens_on_algorithm_change lifespan hook + docker-compose JWT_PRIVATE_KEY/JWT_PUBLIC_KEY + README key-gen snippet + .env.example + version bump 0.1.2
**Wave 2** *(blocked on Wave 1)* — "Remember me" 16h/30d TTL split
- [x] 07.3-03-PLAN.md — create_refresh_token remember_me param + LoginRequest.remember_me + _set_refresh_cookie max_age conditional + LoginView.vue "Stay signed in for 30 days" checkbox + stores/auth.js + api/client.js forwarding + human checkpoint
**Status:** Complete (2026-06-06)
---
### Phase 7.4: Security — Token Fingerprinting / Token Binding (INSERTED)
**Goal**: Add a `fgp` (fingerprint) claim = `hmac(key, User-Agent + Accept-Language)[:16]` to every issued access token. In `get_current_user`, recompute the fingerprint from the request headers and compare with `hmac.compare_digest`. Limits replay of stolen access tokens to the original device/browser context.
**Mode:** quick
**Depends on**: Phase 7.3
**Requirements**: Tracked in `.planning/codebase/CONCERNS.md` §"No Token Fingerprint / Token Binding"
**Plans**: 2 plans
**Wave 0** — Test scaffolds (no production code)
- [x] 07.4-01-PLAN.md — Wave 0 xfail stubs: test_auth_fgp.py (4 stubs covering FGP-01..04)
**Wave 1** *(blocked on Wave 0)* — Production implementation + test promotion
- [x] 07.4-02-PLAN.md — _compute_fgp helper + create_access_token fgp claim + get_current_user fgp validation + login/refresh call site updates + promote all 4 FGP tests
**Status:** Complete (2026-06-06)
---
---
## Milestones
- ✅ **v0.2 — UI Overhaul and Optimization** — Phases 8–11 (shipped 2026-06-17)
<details>
<summary>✅ v0.2 — UI Overhaul and Optimization (Phases 8–11) — SHIPPED 2026-06-17</summary>
- [x] Phase 8: Stack Upgrade & Backend Decomposition (8/8 plans) — completed 2026-06-12
- [x] Phase 9: Admin Panel Rearchitecture (5/5 plans) — completed 2026-06-13
- [x] Phase 10: UX & Interaction (13/13 plans) — completed 2026-06-16
- [x] Phase 11: Visual Design, Responsive Layout & Cleanup (7/7 plans) — completed 2026-06-17
Full archive: `.planning/milestones/v0.2-ROADMAP.md`
</details>
## v0.2 + v0.1 Progress Table
| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 8. Stack Upgrade & Backend Decomposition | v0.2 | 8/8 | Complete | 2026-06-12 |
| 9. Admin Panel Rearchitecture | v0.2 | 5/5 | Complete | 2026-06-13 |
| 10. UX & Interaction | v0.2 | 13/13 | Complete | 2026-06-16 |
| 11. Visual Design, Responsive Layout & Cleanup | v0.2 | 7/7 | Complete | 2026-06-17 |
| 1. Infrastructure Foundation | v0.1 | 5/5 | Complete | 2026-05-22 |
| 2. Users & Authentication | v0.1 | 6/6 | Complete | 2026-06-01 |
| 3. Document Migration & Multi-User Isolation | v0.1 | 5/5 | Complete | 2026-05-25 |
| 4. Folders, Sharing, Quotas & Document UX | v0.1 | 9/9 | Complete | 2026-05-28 |
| 5. Cloud Storage Backends | v0.1 | 12/12 | Complete | 2026-05-30 |
| 6. Performance & Production Hardening | v0.1 | 6/6 | Complete | 2026-05-30 |
| 6.1. Close v1.0 audit gaps | v0.1 | 2/2 | Complete | 2026-05-30 |
| 6.2. Close v1 sharing + cloud-delete + CSV export gaps | v0.1 | 5/5 | Complete | 2026-05-31 |
| 7. Redo and optimize LLM integration | v0.1 | 5/5 | Complete | 2026-06-05 |
| 7.1. Security: session revocation on privilege change | v0.1 | 2/2 | Complete | 2026-06-08 |
| 7.2. Security: JTI claim + Redis access-token revocation | v0.1 | 3/3 | Complete | 2026-06-05 |
| 7.3. Security: ES256 algorithm upgrade | v0.1 | 3/3 | Complete | 2026-06-06 |
| 7.4. Security: token fingerprinting / token binding | v0.1 | 2/2 | Complete | 2026-06-06 |
*Roadmap proposed: 2026-06-17*
.planning/STATE.md
+106 -26
View File
@@ -1,47 +1,75 @@
---
gsd_state_version: 1.0
milestone: v0.2
milestone_name: UI Overhaul and Optimization
current_phase: 11
status: complete
last_updated: "2026-06-17"
last_activity: 2026-06-17 -- v0.2 milestone archived
milestone: v0.3
milestone_name: Reimagining Cloud Storage integration
current_phase: 14
current_phase_name: selective-analysis-and-byte-cache
status: in_progress
stopped_at: Phase 14 Plan 07 complete
last_updated: "2026-06-23T17:55:00.641Z"
last_activity: 2026-06-23
last_activity_desc: Phase 14 Plan 06 byte cache for open/preview/download complete
progress:
total_phases: 4
completed_phases: 4
total_plans: 33
completed_plans: 33
percent: 100
total_phases: 6
completed_phases: 3
total_plans: 30
completed_plans: 29
percent: 50
---
# Project State
**Project:** DocuVault
**Status:** v0.2 milestone complete — ready for next milestone
**Last Updated:** 2026-06-17
**Status:** Phase 14 in progress — Plan 14-06 complete
**Last Updated:** 2026-06-23
## Current Position
Milestone v0.2 shipped 2026-06-17. All 4 phases complete, 40/40 requirements satisfied.
Next action: `/gsd:new-milestone` to define v0.3
Phase: 14 (selective-analysis-and-byte-cache) — IN PROGRESS
Plan: 9 of 9
Status: Plans 14-01 through 14-06 complete. Next: execute 14-07
Last activity: 2026-06-23 — Phase 14 Plan 06 byte cache for open/preview/download complete
## Phase Status
| Phase | Requirements | Status |
|-------|-------------|--------|
| 8. Stack Upgrade & Backend Decomposition | PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08 | **Complete (8/8 plans)** |
| 9. Admin Panel Rearchitecture | ADMIN-08..12, CODE-06, CODE-09 | **Complete (5/5 plans)** |
| 10. UX & Interaction | UX-01..14, CODE-05 | **Complete (13/13 plans)** |
| 11. Visual Design, Responsive Layout & Cleanup | VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, PERF-03 | **Complete (7/7 plans)** |
| 12. Cloud Resource Foundation | CONN-04, CLOUD-01, CLOUD-08, CACHE-01, CACHE-02, SYNC-01 | **Complete** |
| 12.1 Fix Nextcloud Root Listing and Sync Visibility | CONN-04, CLOUD-01, CACHE-01, SYNC-01 | **Complete** |
| 13. Virtual-Local Cloud Operations | CONN-01..03, CLOUD-02..07, CLOUD-09 | **Complete** |
| 14. Selective Analysis and Byte Cache | ANALYZE-01..07, CACHE-03..05 | **Planned** |
| 15. Unified Smart Search | SEARCH-01..07 | **Not started** |
| 16. Change Tracking and Reliability | SYNC-02..04 | **Not started** |
## Performance Metrics
| Metric | Value |
|---|---|
| Phases complete | 4 / 4 |
| Requirements satisfied | 40 / 40 |
| Plans complete | 33 / 33 |
| Tests at close | 277 |
| Phases complete | 3 / 6 |
| Requirements satisfied | 17 / 36 |
| Plans complete | 21 / 21 |
| Tests at milestone start | 277 |
| Phase 12.1 P01 | 823s | 4 tasks | 14 files |
| Phase 12.1 P02 | 2100s | 3 tasks | 13 files |
| Phase 12.1 P03 | 677s | 4 tasks | 11 files |
| Phase 12.1 P04 | 15m | 4 tasks | 10 files |
| Phase 13 P02 | 30m | 2 tasks | 6 files |
| Phase 13 P03 | 134s | 2 tasks | 8 files |
| Phase 13 P04 | 180m | 2 tasks | 7 files |
| Phase 13 P06 | 5m | 2 tasks | 3 files |
| Phase 13 P07 | 30m | 2 tasks | 5 files |
| Phase 13 P08 | 20m | 2 tasks | 2 files |
| Phase 13 P09 | 30m | 2 tasks | 3 files |
| Phase 13 P10 | 25m | 2 tasks | 6 files |
| Phase 13 P11 | 20m | 2 tasks | 6 files |
| Phase 14 P01 | 15m | 2 tasks | 5 files |
| Phase 14 P02 | 12m | 2 tasks | 5 files |
| Phase 14 P03 | 14m | - tasks | - files |
| Phase 14 P04 | 12m | 2 tasks | 4 files |
| Phase 14 P05 | 10m | 2 tasks | 4 files |
| Phase 14 P06 | 10m | 2 tasks | 5 files |
| Phase 14 P07 | 12m | 2 tasks | 4 files |
| Phase 14 P08 | 10m | 2 tasks | 3 files |
## Accumulated Context
@@ -60,12 +88,18 @@ Next action: `/gsd:new-milestone` to define v0.3
| to.matched.some() for requiresAdmin guard | Vue Router 4 does not inherit meta to children; direct to.meta check is a security regression |
| FastAPI 0.128+ empty-path sub-router restriction | `@router.get("")` on sub-router with empty include prefix fails; register root routes on parent aggregator |
| Vite 6 upgrade resolves 2 CVEs | CVE-2026-39363/39364 closed; npm audit now clean |
| Phase 13 mutation JSONResponse | Mutations return JSONResponse (not HTTPException) so kind/reason appear at response top level |
| Phase 13 cloud_operations.py orchestration | All mutation logic routes through services/cloud_operations.py — never inline in routers |
| testCloudConnection explicit-only | Never called as navigation side effect (D-13); only from user action or post-failure retest |
| v0.3.0 version bump | Phase 13 completion warrants minor version bump per CLAUDE.md versioning protocol |
### Roadmap Evolution
- v0.1 completed: all 7 foundation phases + security hardening (2026-06-06)
- v0.2 completed: UI overhaul, admin panel rearchitecture, responsive layout, codebase quality (2026-06-17)
- v0.2 archived to `.planning/milestones/v0.2-ROADMAP.md`
- v0.3 in progress: Phase 12 (cloud resource foundation) complete 2026-06-21; Phase 12.1 (Nextcloud fix) complete; Phase 13 (virtual-local cloud operations) complete 2026-06-23 — v0.3.0 shipped
- Phase 14 (selective analysis and byte cache) planned 2026-06-23
### Open Questions
@@ -77,11 +111,57 @@ None.
## Session Continuity
**Stopped at:** Phase 14 Plan 07 complete
_Updated at each phase transition._
| Field | Value |
|---|---|
| Last session | 2026-06-17 — v0.2 milestone archived |
| Next action | /gsd:new-milestone to define v0.3 |
| Last session | 2026-06-23T17:54:00.317Z |
| Next action | Execute 14-07 |
| Pending decisions | None |
| Resume file | None |
| Resume file | .planning/phases/14-selective-analysis-and-byte-cache/14-08-PLAN.md |
## Decisions
- [Phase 12]: Remove NextcloudBackend.list_folder override — inherit canonical WebDAVBackend method
- [Phase 12]: OneDrive nextLink restricted to graph.microsoft.com host
- [Phase 12]: apply_listing_and_finalize is the single freshness gate — callers must not set refresh_state=fresh independently after list_folder
- [Phase 12.1 P03]: Named route objects used for all cloud folder navigation — Vue Router handles opaque ref encoding
- [Phase 12.1 P03]: Breadcrumb lineage maintained as explicit visited-node list — never reconstructed from provider_item_id
- [Phase 12.1 P03]: provider_item_id is canonical navigation reference; DocuVault id is row identity for Vue keys and metadata only
- [Phase 13 P03]: Backend-typed bodies required; frontend never guesses
- [Phase 13 P04]: file-open must call openCloudFile API; window.open() to provider URL is forbidden (D-02/T-13-07)
- [Phase 13 P10]: connectionHealth store translation is single source for browser compact status and Settings diagnostics (D-12)
- [Phase 13 P10]: testCloudConnection never called as side effect of folder browse navigation (D-13)
- [Phase 13 P04]: D-17: Google Drive OAuth uses drive scope (not drive.file) for Phase 13 full-access mutations
- [Phase 13 P07]: D-18: Preview is binary-only (PDF/images); Office/Workspace formats use typed unsupported_preview fallback to authorized download endpoint
- [Phase 13 P03]: Phase 13 mutation errors use JSONResponse (not HTTPException) so kind/reason appear at top level of response body, not nested under detail
- [Phase 13 P06]: upload_mutated folder state code: upload success marks parent folder as warning/upload_mutated for reconcile-before-return
- [Phase 13 P07]: CloudFolderView uses api.* barrel imports so vi.mock intercepts correctly
- [Phase 13 P07]: UploadProgress suppressed in cloud mode (v-if) — cloud queue dialogs replace it per D-03/D-04
- [Phase 13 P07]: StorageBrowser emits upload-queue-resolve with typed action; CloudFolderView handles all five resolution paths (keep_both/replace/skip/retry/cancel_all)
- [Phase 13 P08]: Rename collision surfaced to user (no auto-retry) — user chose name explicitly
- [Phase 13 P08]: Create-folder bounded retry up to 5 attempts with keep_both_name counter suffix D-05/D-06
- [Phase 13 P08]: Stale guard for create-folder and rename calls update_folder_state before returning typed stale body D-07
- [Phase 13 P08]: Reconcile-before-return for create-folder and rename: upsert_cloud_item + update_folder_state T-13-26
- [Phase 13 P09]: Move with descendant-chain walk + self-check + cross-connection check before provider submission
- [Phase 13 P09]: Stale move guard stops mutation, refreshes source folder state, returns typed stale result
- [Phase 13 P09]: Delete audit metadata: only kind/provider_item_id/display_name/is_folder — no bytes or credentials
- [Phase 13 P11]: Version bump to v0.3.0 on Phase 13 completion (minor bump for full phase per CLAUDE.md protocol)
- [Phase 14 P02]: compute_version_key defined in cloud_analysis_versioning.py and re-exported from cloud_cache.py — single import site for tests and callers
- [Phase 14 P02]: content_hash is optional post-hydration supplement, never a pre-download precondition (D-20)
- [Phase 14 P02]: evict_lru_entries stamps evicted_at only; caller owns MinIO deletion and quota decrement (separation of concerns)
- [Phase 14 P02]: user_analysis_settings is distinct from system_settings — single authority for per-user analysis preferences
- [Phase ?]: [Phase 14 P03]: retain_or_reuse_cache_entry reactivates evicted rows — unique constraint prevents duplicate insert for same version_key
- [Phase ?]: [Phase 14 P03]: api/cloud/analysis.py as aggregator router so Plan 01 RED tests can import before all routes implemented
- [Phase ?]: [Phase 14 P03]: CacheStatusOut enforces T-14-02/T-14-08 by design — object_key absent at type level
- [Phase ?]: Phase 14 P04: estimate_scope uses durable cloud_items metadata only (T-14-04)
- [Phase ?]: Phase 14 P04: live_metadata_changed flag bypasses already-current fallback when provider confirms etag changed
- [Phase ?]: Phase 14 P04: AnalysisJobOut per-stage counts always int (never None)
- [Phase 14 P06]: hydrate_and_cache_bytes is the single cache lifecycle entry point for preview/download — never inline adapter.get_object in open/preview/download routes
- [Phase 14 P06]: preview and download cache integration is backend-transparent — response shapes unchanged from Phase 13 (T-14-02)
- [Phase ?]: [Phase 14 P07]: analyze-file button in name cell not file-row-actions
- [Phase ?]: [Phase 14 P07]: translateAnalysisStatus is single status translation source in cloudConnections store
- [Phase ?]: [Phase 14 P08]: getCacheSettings corrected to /api/cloud/analysis/cache; tierCapBytes drives Settings cache limit max
- [Phase ?]: [Phase 14 P08]: Analysis Settings section in SettingsCloudTab - separate card with cache limit input, progress detail toggle, failure behavior toggle
.planning/debug/phase-12-cloud-schema-cold-start.md
+49
View File
@@ -0,0 +1,49 @@
# Debug: Phase 12 Cloud Schema Cold Start
**Status:** root cause found
**Date:** 2026-06-19
**UAT tests:** 1, 2
## Symptoms
- `GET /api/cloud/connections` raises `psycopg.errors.UndefinedColumn` for `cloud_connections.display_name_override`.
- `POST /api/cloud/connections/webdav` reaches `_upsert_cloud_connection` and raises the same error, preventing Nextcloud account connection.
## Root Cause
The running application code and ORM are at Phase 12, but the live PostgreSQL schema remains at Alembic revision `0005`.
Live evidence:
```text
$ docker compose run --rm backend alembic current
0005
```
Migration `backend/migrations/versions/0006_cloud_resource_foundation.py` correctly adds `cloud_connections.display_name_override` and the Phase 12 cloud metadata tables. The ORM correctly maps that column. The defect is that `docker-compose.yml` has no migration service and the backend command starts Uvicorn directly. Backend, Celery worker, and Celery beat depend on PostgreSQL health, but none depends on `alembic upgrade head` completing. Therefore `docker compose up` can run new application code against an old persistent database.
## Why Automated Tests Missed It
- Most backend tests build schema directly from `Base.metadata.create_all`, which validates the final ORM shape but bypasses Alembic history and deployment ordering.
- Existing Alembic tests target early migrations and do not exercise an existing PostgreSQL database upgraded from `0005` to `head`.
- Phase verification checked migration file structure and model parity, not a real cold-start Compose upgrade path.
## Files Involved
- `docker-compose.yml` — no one-shot migration service; backend/workers start after DB health only.
- `backend/migrations/versions/0006_cloud_resource_foundation.py` — contains the required column and tables but was not applied.
- `backend/db/models.py` — queries `display_name_override`, exposing schema drift immediately.
- `backend/tests/test_alembic.py` — lacks a 0005-to-head PostgreSQL upgrade regression.
- `.planning/phases/12-cloud-resource-foundation/12-VALIDATION.md` — cold-start test expected migration completion, but execution evidence did not actually verify Compose migration orchestration.
## Required Fix Direction
1. Add a one-shot Compose migration service that runs `alembic upgrade head` with `DATABASE_MIGRATE_URL` after PostgreSQL becomes healthy.
2. Make backend, Celery worker, and Celery beat wait for that migration service to complete successfully.
3. Add a PostgreSQL/Compose regression proving an existing revision `0005` advances to `0006/head` before the API starts, and assert `display_name_override`, `cloud_items`, `cloud_item_topics`, and `cloud_folder_states` exist.
4. Document the migration lifecycle and recovery command in README/RUNBOOK.
5. For the currently running environment, apply `alembic upgrade head` and restart application processes before resuming UAT.
## Scope
Both UAT blockers share this root cause. No evidence currently indicates a separate Nextcloud credential or WebDAV defect.
.planning/debug/resolved/phase-12-cloud-schema-cold-start.md
+49
View File
@@ -0,0 +1,49 @@
# Debug: Phase 12 Cloud Schema Cold Start
**Status:** root cause found
**Date:** 2026-06-19
**UAT tests:** 1, 2
## Symptoms
- `GET /api/cloud/connections` raises `psycopg.errors.UndefinedColumn` for `cloud_connections.display_name_override`.
- `POST /api/cloud/connections/webdav` reaches `_upsert_cloud_connection` and raises the same error, preventing Nextcloud account connection.
## Root Cause
The running application code and ORM are at Phase 12, but the live PostgreSQL schema remains at Alembic revision `0005`.
Live evidence:
```text
$ docker compose run --rm backend alembic current
0005
```
Migration `backend/migrations/versions/0006_cloud_resource_foundation.py` correctly adds `cloud_connections.display_name_override` and the Phase 12 cloud metadata tables. The ORM correctly maps that column. The defect is that `docker-compose.yml` has no migration service and the backend command starts Uvicorn directly. Backend, Celery worker, and Celery beat depend on PostgreSQL health, but none depends on `alembic upgrade head` completing. Therefore `docker compose up` can run new application code against an old persistent database.
## Why Automated Tests Missed It
- Most backend tests build schema directly from `Base.metadata.create_all`, which validates the final ORM shape but bypasses Alembic history and deployment ordering.
- Existing Alembic tests target early migrations and do not exercise an existing PostgreSQL database upgraded from `0005` to `head`.
- Phase verification checked migration file structure and model parity, not a real cold-start Compose upgrade path.
## Files Involved
- `docker-compose.yml` — no one-shot migration service; backend/workers start after DB health only.
- `backend/migrations/versions/0006_cloud_resource_foundation.py` — contains the required column and tables but was not applied.
- `backend/db/models.py` — queries `display_name_override`, exposing schema drift immediately.
- `backend/tests/test_alembic.py` — lacks a 0005-to-head PostgreSQL upgrade regression.
- `.planning/phases/12-cloud-resource-foundation/12-VALIDATION.md` — cold-start test expected migration completion, but execution evidence did not actually verify Compose migration orchestration.
## Required Fix Direction
1. Add a one-shot Compose migration service that runs `alembic upgrade head` with `DATABASE_MIGRATE_URL` after PostgreSQL becomes healthy.
2. Make backend, Celery worker, and Celery beat wait for that migration service to complete successfully.
3. Add a PostgreSQL/Compose regression proving an existing revision `0005` advances to `0006/head` before the API starts, and assert `display_name_override`, `cloud_items`, `cloud_item_topics`, and `cloud_folder_states` exist.
4. Document the migration lifecycle and recovery command in README/RUNBOOK.
5. For the currently running environment, apply `alembic upgrade head` and restart application processes before resuming UAT.
## Scope
Both UAT blockers share this root cause. No evidence currently indicates a separate Nextcloud credential or WebDAV defect.
.planning/phases/08-stack-upgrade-backend-decomposition/08-01-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-01-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-01-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-01-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-02-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-02-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-02-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-02-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-03-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-03-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-03-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-03-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-04-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-04-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-04-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-04-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-05-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-05-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-05-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-05-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-06-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-06-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-06-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-06-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-07-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-07-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-07-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-07-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-08-PLAN.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-08-PLAN.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-08-SUMMARY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-08-SUMMARY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-CONTEXT.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-CONTEXT.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-DISCUSSION-LOG.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-DISCUSSION-LOG.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-PATTERNS.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-PATTERNS.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-RESEARCH.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-RESEARCH.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-SECURITY.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-SECURITY.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-UAT.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-UAT.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-UI-SPEC.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-UI-SPEC.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-VALIDATION.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-VALIDATION.md
View File
.planning/phases/08-stack-upgrade-backend-decomposition/08-VERIFICATION.md → .planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-VERIFICATION.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-01-PLAN.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-01-PLAN.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-01-SUMMARY.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-01-SUMMARY.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-02-PLAN.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-02-PLAN.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-02-SUMMARY.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-02-SUMMARY.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-03-PLAN.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-03-PLAN.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-03-SUMMARY.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-03-SUMMARY.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-04-PLAN.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-04-PLAN.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-04-SUMMARY.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-04-SUMMARY.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-05-PLAN.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-05-PLAN.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-05-SUMMARY.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-05-SUMMARY.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-CONTEXT.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-CONTEXT.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-DISCUSSION-LOG.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-DISCUSSION-LOG.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-PATTERNS.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-PATTERNS.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-RESEARCH.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-RESEARCH.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-REVIEW.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-REVIEW.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-SECURITY.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-SECURITY.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-UAT.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-UAT.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-VALIDATION.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-VALIDATION.md
View File
.planning/phases/09-admin-panel-rearchitecture/09-VERIFICATION.md → .planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-VERIFICATION.md
View File
.planning/phases/10-ux-interaction/10-01-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-01-PLAN.md
View File
.planning/phases/10-ux-interaction/10-01-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-01-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-02-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-02-PLAN.md
View File
.planning/phases/10-ux-interaction/10-02-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-02-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-03-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-03-PLAN.md
View File
.planning/phases/10-ux-interaction/10-03-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-03-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-04-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-04-PLAN.md
View File
.planning/phases/10-ux-interaction/10-04-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-04-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-05-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-05-PLAN.md
View File
.planning/phases/10-ux-interaction/10-05-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-05-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-06-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-06-PLAN.md
View File
.planning/phases/10-ux-interaction/10-06-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-06-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-07-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-07-PLAN.md
View File
.planning/phases/10-ux-interaction/10-07-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-07-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-08-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-08-PLAN.md
View File
.planning/phases/10-ux-interaction/10-08-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-08-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-09-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-09-PLAN.md
View File
.planning/phases/10-ux-interaction/10-09-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-09-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-10-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-10-PLAN.md
View File
.planning/phases/10-ux-interaction/10-10-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-10-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-11-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-11-PLAN.md
View File
.planning/phases/10-ux-interaction/10-11-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-11-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-12-PLAN.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-12-PLAN.md
View File
.planning/phases/10-ux-interaction/10-12-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-12-SUMMARY.md
View File
.planning/milestones/v0.2-phases/10-ux-interaction/10-13-PLAN.md
+393
View File
@@ -0,0 +1,393 @@
---
phase: 10-ux-interaction
plan: 13
type: execute
wave: 1
depends_on: []
files_modified:
- frontend/src/components/ui/TreeItem.vue
- frontend/src/components/storage/StorageBrowser.vue
- frontend/src/App.vue
- frontend/src/components/documents/SearchBar.vue
- frontend/src/components/layout/OsDragOverlay.vue
- frontend/src/__tests__/keyboard.test.js
- frontend/src/components/ui/__tests__/TreeItem.test.js
- frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js
autonomous: true
requirements: [UX-02, UX-03, UX-05, UX-06, UX-07, UX-08, UX-09]
gap_closure: true
must_haves:
truths:
- "Sidebar Cloud/Folder sections show animated shimmer rows while async data loads — no 'Loading…' text visible"
- "Admin routes (/admin/*) render with no AppSidebar — AdminLayout is the sole layout component"
- "Pressing '/', 'U', or 'N' in the file manager dispatches to the actual FileManagerView instance — not a RouterView proxy"
- "Pressing Escape in the search input clears the field and preserves focus — no browser-native blur"
- "Dropping an OS file on the drag overlay triggers upload — capture-phase window listener fires before folder-row handlers"
- "Search bar and sort controls are visible at the root of both local and cloud file browsers"
artifacts:
- path: "frontend/src/components/ui/TreeItem.vue"
provides: "Three animate-pulse shimmer rows in the v-if='loading' branch"
contains: "animate-pulse"
- path: "frontend/src/components/storage/StorageBrowser.vue"
provides: "showSearch computed returns true for mode === 'local' OR mode === 'cloud'"
- path: "frontend/src/App.vue"
provides: "Third template branch for admin routes (no AppSidebar); getFileManagerInstance() via matched.find for keyboard dispatch"
- path: "frontend/src/components/documents/SearchBar.vue"
provides: "@keydown.escape.prevent.stop suppresses browser native blur on type='search'"
- path: "frontend/src/components/layout/OsDragOverlay.vue"
provides: "window drop listener registered with capture=true; removeEventListener also passes true"
key_links:
- from: "frontend/src/App.vue (onKeydown)"
to: "FileManagerView.focusSearch / triggerUpload / startNewFolder"
via: "router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default"
pattern: "instances\\.default"
- from: "frontend/src/components/layout/OsDragOverlay.vue"
to: "window drop event"
via: "addEventListener('drop', handler, true)"
pattern: "addEventListener.*drop.*true"
---
<objective>
Close all 6 UAT gaps from 10-UAT.md that block Phase 10 sign-off: sidebar shimmer (Gap 1), search-at-root visibility (Gap 2), admin sidebar bleed (Gap 3), keyboard shortcuts broken by RouterView proxy (Gap 4 — covers tests 11, 12, 13), Escape-breaks-search (Gap 5), and OS drag-drop not uploading (Gap 6).
Purpose: Phase 10 is recorded complete in ROADMAP.md but UAT (10-UAT.md) shows 9 issues with 6 distinct root causes diagnosed. These targeted fixes close all 6 causes with minimal code change, restoring full UAT pass.
Output: Five production files modified, three test files added. No new dependencies. No regressions.
</objective>
<execution_context>
@/Users/nik/.claude/get-shit-done/workflows/execute-plan.md
@/Users/nik/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@/Users/nik/Documents/Progamming/document_scanner/.planning/PROJECT.md
@/Users/nik/Documents/Progamming/document_scanner/.planning/ROADMAP.md
@/Users/nik/Documents/Progamming/document_scanner/.planning/STATE.md
@/Users/nik/Documents/Progamming/document_scanner/.planning/phases/10-ux-interaction/10-UAT.md
<interfaces>
<!-- Key contracts the executor needs. Extracted from codebase. No codebase exploration needed. -->
From frontend/src/App.vue (current full state — relevant sections):
```html
<!-- Template — only two branches today: -->
<AuthLayout v-if="route.meta.layout === 'auth'" />
<div v-else class="flex h-screen overflow-hidden">
<AppSidebar />
<main class="flex-1 overflow-y-auto">
<router-view ref="routeViewRef" /> <!-- resolves to RouterView proxy, NOT FileManagerView -->
</main>
</div>
<ToastContainer />
<OsDragOverlay @files-dropped="onOsFilesDropped" />
```
```js
// script setup
import { ref, onMounted, onUnmounted } from 'vue'
import { useRoute } from 'vue-router'
const route = useRoute()
const routeViewRef = ref(null) // ← remove this
function onOsFilesDropped(files) {
routeViewRef.value?.handleOsDrop?.(files) // ← fix to use getFileManagerInstance()
}
function onKeydown(e) {
// guard: INPUT/TEXTAREA/SELECT/contentEditable + dialog check omitted here
routeViewRef.value?.focusSearch?.() // line 37 ← fix
routeViewRef.value?.clearSearch?.() // line 40 ← fix
routeViewRef.value?.triggerUpload?.() // line 43 ← fix
routeViewRef.value?.startNewFolder?.() // line 46 ← fix
}
```
From frontend/src/router/index.js — admin route meta:
```js
{
path: '/admin',
component: () => import('../layouts/AdminLayout.vue'),
meta: { requiresAdmin: true }, // only on parent; children resolved via matched.some()
children: [/* AdminOverviewView, AdminUsersView, AdminQuotasView, AdminAiView, AdminAuditView */]
}
```
From frontend/src/components/ui/TreeItem.vue — loading branch to replace (lines 48-52):
```html
<div
v-if="loading"
class="text-xs text-gray-400 py-1"
:style="{ paddingLeft: `${(depth + 1) * 12 + 8}px` }"
>
Loading…
</div>
```
Shimmer pattern to replicate (from AppSidebar.vue lines 60-64):
```html
<div v-if="loadingRoots" class="pl-7 py-1 space-y-1">
<div v-for="n in 3" :key="`sk-f-${n}`" class="flex items-center gap-2 py-1">
<div class="w-4 h-4 bg-gray-100 rounded animate-pulse shrink-0"></div>
<div class="h-3 bg-gray-100 rounded animate-pulse" :style="{ width: (50 + n * 15) + 'px' }"></div>
</div>
</div>
```
From frontend/src/components/storage/StorageBrowser.vue line 287:
```js
const showSearch = computed(() => props.mode === 'local' && props.breadcrumb.length > 0)
// TARGET STATE:
const showSearch = computed(() => props.mode === 'local' || props.mode === 'cloud')
```
From frontend/src/components/documents/SearchBar.vue line 11:
```html
@keydown.escape="emit('update:modelValue', '')"
<!-- TARGET STATE: -->
@keydown.escape.prevent.stop="emit('update:modelValue', '')"
```
From frontend/src/components/layout/OsDragOverlay.vue (Options API — lines 52-63):
```js
mounted() {
window.addEventListener('dragenter', this.onDragEnter)
window.addEventListener('dragleave', this.onDragLeave)
window.addEventListener('dragover', this.onDragOver)
window.addEventListener('drop', this.onDrop) // ← bubble phase; must become capture
},
beforeUnmount() {
window.removeEventListener('dragenter', this.onDragEnter)
window.removeEventListener('dragleave', this.onDragLeave)
window.removeEventListener('dragover', this.onDragOver)
window.removeEventListener('drop', this.onDrop) // ← must match with true
}
```
From frontend/src/views/FileManagerView.vue defineExpose (lines 190-196):
```js
// These ARE correct — all methods are exposed. The problem is App.vue never reaches this instance.
defineExpose({
focusSearch: () => browserRef.value?.focusSearch?.(),
triggerUpload: () => browserRef.value?.triggerUpload?.(),
startNewFolder: () => browserRef.value?.startNewFolder?.(),
clearSearch: () => browserRef.value?.clearSearch?.(),
handleOsDrop: (files) => onFilesSelected({ files, autoClassify: true }),
})
```
From frontend/src/__tests__/keyboard.test.js (existing structure):
Uses mountFileManager() helper, vi.mock('../api/client.js', ...), vi.mock('../stores/auth.js', ...),
vi.mock('../stores/topics.js', ...), setActivePinia(createPinia()), createRouter+createMemoryHistory.
</interfaces>
</context>
<tasks>
<task type="auto">
<name>Task 1: Sidebar shimmer rows (TreeItem.vue) and search-at-root (StorageBrowser.vue)</name>
<files>
frontend/src/components/ui/TreeItem.vue
frontend/src/components/storage/StorageBrowser.vue
</files>
<action>
TreeItem.vue — replace the v-if="loading" div (lines 48-52) with a shimmer block. The replacement wraps three shimmer rows in a single container div. Apply the indent :style on the container (same binding the removed div had: `{ paddingLeft: \`\${(depth + 1) * 12 + 8}px\` }`). The container also gets `class="py-1 space-y-1"`. Each of the three inner rows uses `class="flex items-center gap-2 py-1"` and contains two children:
- Icon placeholder: `class="w-4 h-4 bg-gray-100 rounded animate-pulse shrink-0"`
- Text placeholder: `class="h-3 bg-gray-100 rounded animate-pulse"` with `:style="{ width: (50 + n * 15) + 'px' }"`
Use `v-for="n in 3"` with `:key="\`sk-t-\${n}\`"` on the inner row div.
Do not change any other branch (v-else-if loadError, v-else-if children.length===0, slot children) or any script section.
StorageBrowser.vue — change line 287 only. Change:
`const showSearch = computed(() => props.mode === 'local' && props.breadcrumb.length > 0)`
to:
`const showSearch = computed(() => props.mode === 'local' || props.mode === 'cloud')`
No template changes needed — SearchBar and SortControls already share v-if="showSearch".
</action>
<verify>
<automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep -c "animate-pulse" src/components/ui/TreeItem.vue && grep "showSearch" src/components/storage/StorageBrowser.vue | grep "cloud"</automated>
</verify>
<done>
- `grep -c "animate-pulse" src/components/ui/TreeItem.vue` returns at least 2
- `grep -c "Loading" src/components/ui/TreeItem.vue` returns 0
- `grep "showSearch" src/components/storage/StorageBrowser.vue` contains `props.mode === 'cloud'`
</done>
</task>
<task type="auto">
<name>Task 2: Admin sidebar bleed and keyboard instance resolution (App.vue)</name>
<files>frontend/src/App.vue</files>
<action>
Two root causes, one file. Apply both changes together.
CHANGE A — Admin sidebar bleed (Gap 3):
Insert a v-else-if branch in the template between the auth branch and the user-layout div. The new branch condition is `route.matched.some(r => r.meta.requiresAdmin)`. When true it renders only `<router-view />` — no AppSidebar, no main wrapper. The complete corrected template root (inside the component root, excluding ToastContainer and OsDragOverlay which stay unchanged):
1. `<AuthLayout v-if="route.meta.layout === 'auth'" />`
2. `<router-view v-else-if="route.matched.some(r => r.meta.requiresAdmin)" />`
3. `<div v-else class="flex h-screen overflow-hidden">` ... AppSidebar + main + router-view (no ref attribute) ... `</div>`
Note: the router-view in branch 3 must NOT carry `ref="routeViewRef"` — refs on router-view resolve to the RouterView proxy (same root cause as Gap 4). Remove the ref attribute.
CHANGE B — Keyboard instance resolution (Gap 4, also fixes tests 12 and 13):
The `routeViewRef` ref and its usage must be replaced with a direct instance lookup:
1. Add `useRouter` to the `vue-router` import: `import { useRoute, useRouter } from 'vue-router'`
2. Add `const router = useRouter()` after `const route = useRoute()`
3. Add helper: `function getFileManagerInstance() { return router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default ?? null }`
4. Remove `const routeViewRef = ref(null)` — no longer used
5. Remove `ref` from the `ref` import if it is now unused (check — ref was only used for routeViewRef)
6. Replace all `routeViewRef.value?.X?.()` calls in onKeydown with `getFileManagerInstance()?.X?.()`
7. Replace `routeViewRef.value?.handleOsDrop?.(files)` in onOsFilesDropped with `getFileManagerInstance()?.handleOsDrop?.(files)`
After both changes, `ref` from vue should be removed from the import line if nothing else uses it (check first — if ToastContainer or OsDragOverlay use a local ref, keep it; otherwise remove to avoid lint warnings).
</action>
<verify>
<automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep "routeViewRef" src/App.vue; echo "exit:$?"; grep "instances.default" src/App.vue; grep "requiresAdmin" src/App.vue</automated>
</verify>
<done>
- `grep "routeViewRef" src/App.vue` returns no output (fully removed)
- `grep "instances.default" src/App.vue` returns the getFileManagerInstance() line
- `grep "requiresAdmin" src/App.vue` returns the v-else-if template branch
- `grep "useRouter" src/App.vue` appears in import and instantiation
</done>
</task>
<task type="auto">
<name>Task 3: Escape modifier (SearchBar.vue) and capture-phase drop (OsDragOverlay.vue)</name>
<files>
frontend/src/components/documents/SearchBar.vue
frontend/src/components/layout/OsDragOverlay.vue
</files>
<action>
SearchBar.vue — one character change on line 11. Add `.prevent.stop` modifiers to `@keydown.escape`:
Before: `@keydown.escape="emit('update:modelValue', '')"`
After: `@keydown.escape.prevent.stop="emit('update:modelValue', '')"`
`.prevent` stops the browser's native clear+blur behavior on type="search" inputs. `.stop` stops bubbling to App.vue's global keydown handler (which would call clearSearch() a second time). No other changes.
OsDragOverlay.vue — two lines change in the Options API lifecycle hooks:
In mounted(): change `window.addEventListener('drop', this.onDrop)` to `window.addEventListener('drop', this.onDrop, true)`
In beforeUnmount(): change `window.removeEventListener('drop', this.onDrop)` to `window.removeEventListener('drop', this.onDrop, true)`
The third argument `true` registers the listener in capture phase, meaning it runs before any bubble-phase handlers on child elements (including `@drop.prevent` on folder rows in StorageBrowser.vue). The removeEventListener MUST also pass `true` — EventTarget tracks bubble-phase and capture-phase registrations separately, so without `true` the cleanup call would fail silently and the listener would leak.
Do not change dragenter, dragleave, or dragover listeners — those remain in bubble phase and work correctly.
</action>
<verify>
<automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep "keydown.escape" src/components/documents/SearchBar.vue && grep -n "addEventListener.*drop\|removeEventListener.*drop" src/components/layout/OsDragOverlay.vue</automated>
</verify>
<done>
- `grep "keydown.escape" src/components/documents/SearchBar.vue` shows `.prevent.stop` in the modifier chain
- `grep "addEventListener.*drop" src/components/layout/OsDragOverlay.vue` shows `true` as third argument
- `grep "removeEventListener.*drop" src/components/layout/OsDragOverlay.vue` shows `true` as third argument
</done>
</task>
<task type="auto" tdd="true">
<name>Task 4: Regression tests for all 6 gaps</name>
<files>
frontend/src/__tests__/keyboard.test.js
frontend/src/components/ui/__tests__/TreeItem.test.js
frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js
</files>
<behavior>
TreeItem shimmer:
- When loading=true and expanded=true → rendered HTML contains elements with class "animate-pulse"
- When loading=true and expanded=true → text "Loading" does not appear in rendered HTML
StorageBrowser showSearch:
- mode='local', breadcrumb=[] → showSearch is true (root-level local, previously false)
- mode='local', breadcrumb=[{name:'Folder'}] → showSearch is true (non-root local)
- mode='cloud', breadcrumb=[] → showSearch is true (cloud root, previously always false)
- mode='shared' → showSearch is false
App.vue keyboard dispatch:
- matched.find(r => r.instances?.default)?.instances?.default on a mounted FileManagerView router returns an object with focusSearch defined
</behavior>
<action>
keyboard.test.js — append a new describe block at the end of the existing file (do not modify or move existing describes):
"Gap 4: getFileManagerInstance resolves to actual component, not RouterView proxy" — using the existing mountFileManager() helper and makeRouter(), after mounting FileManagerView and flushing promises, access `router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default` and assert that it is not null and has a `focusSearch` property. This proves the resolution mechanism the refactored App.vue uses is correct. Import `useRouter` from vue-router at the top if not already imported — check existing imports first.
TreeItem.test.js — create at `frontend/src/components/ui/__tests__/TreeItem.test.js`:
- Import: `describe, it, expect, vi` from vitest; `mount, flushPromises` from @vue/test-utils; TreeItem from the component
- Mock AppIcon: `vi.mock('../AppIcon.vue', () => ({ default: { template: '<span/>' } }))`
- Helper: `mountExpanded(overrides = {})` — mounts TreeItem with `label="Test"`, `loadChildren: vi.fn().mockResolvedValue([])`, `expandable: true` and spreads overrides. After mount, call `w.vm.toggleExpand()` via `w.vm.$.setupState.toggleExpand()` (or trigger the expand button click) and flush promises to reach expanded state with children loaded.
- For the loading=true test: mount with a loadChildren that returns a promise that never resolves (`new Promise(() => {})`). Click the expand button to trigger load. Before flushing, assert the HTML. The loading ref will be true while the promise is pending.
- describe "Gap 1: sidebar shimmer rows": two tests as per behavior block above.
- describe "Gap 1 regression: non-loading branches unchanged": one test asserting that with loadChildren resolving to [] and expanded, the "Empty" text appears (sibling v-else-if branch guard).
StorageBrowser.showSearch.test.js — create at `frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js`:
- Heavy stub setup: all child components that StorageBrowser imports must be stubbed (SearchBar, SortControls, DocumentCard, FolderRow, EmptyState, AppIcon, BreadcrumbBar, DropZone, etc.) — use `stubs: { SearchBar: true, SortControls: true, ... }` in global mount options or individual vi.mock calls.
- Mock all API calls used on mount (listDocuments, listFolders, etc.) via vi.mock('../../../api/client.js', ...).
- After mount with given props, access `w.vm.showSearch` directly as a computed.
- Props for mount: at minimum `mode`, `breadcrumb`, `documents: []`, `folders: []`, `topicColorFn: () => '#000'`, `loading: false`.
- Four it() blocks as per behavior block above.
- Wrap in `describe("Gap 2: showSearch visible at root for local and cloud modes", ...)`.
All new tests run as part of `npm run test -- --run` without additional flags.
</action>
<verify>
<automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && npm run test -- --reporter=verbose --run 2>&1 | grep -E "(PASS|FAIL|SKIP| ✓ | × | ✗ )" | tail -50</automated>
</verify>
<done>
- All new describe blocks appear in output with passing test indicators
- `npm run test -- --run` exits 0 with zero failures
- `grep -c "animate-pulse" src/components/ui/__tests__/TreeItem.test.js` returns at least 1
- `grep -c "showSearch" src/components/storage/__tests__/StorageBrowser.showSearch.test.js` returns at least 4
</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| OS file drag → window drop (capture) | Files arrive via browser DataTransfer API — browser-enforced; no network boundary crossed; payload handled only client-side before going through existing authenticated upload flow |
| Admin route layout selection | Template branch selection is display-only — backend enforces admin access via get_current_admin dep on every admin endpoint; changing template rendering creates no auth regression |
## STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-10gc-01 | Tampering | OsDragOverlay capture-phase drop handler | accept | Handler reads only e.dataTransfer.files (browser-controlled), resets overlay state, emits to parent — no direct server interaction; upload goes through existing authenticated API path unchanged |
| T-10gc-02 | Spoofing | router.currentRoute.value.matched.find().instances.default | accept | Read-only Vue internals lookup; no user-supplied data flows through this path; cannot be spoofed via URL manipulation — Vue populates instances after component mount, not from route params |
| T-10gc-03 | Elevation of Privilege | App.vue v-else-if admin branch | accept | Branch adds a missing layout guard (removes AppSidebar for admin); it does not grant or deny route access — navigation guard in router/index.js is unchanged and continues to enforce requiresAdmin check |
| T-10gc-SC | Tampering | npm/pip/cargo installs | accept | No new packages installed — all fixes are template/script edits to existing files |
</threat_model>
<verification>
Manual UAT re-run checklist (all must pass before marking complete):
Gap 1 — Sidebar shimmer: Expand a cloud provider tree item in the sidebar while data loads. Animated shimmer rows appear; "Loading…" text is absent.
Gap 2 — Search at root: Navigate to / (file manager root, no folder entered). Search bar and sort controls are visible in the content area header.
Gap 3 — Admin sidebar: Navigate to /admin/users in a logged-in admin session. Only the AdminLayout and AdminSidebar render — AppSidebar (user nav) is absent.
Gap 4 — Keyboard shortcuts: With the file manager at root, press '/'. Search bar receives cursor focus. Press 'U'. File picker dialog opens. Press 'N'. New folder inline input appears.
Gap 5 — Escape behavior: Type text into the search bar. Press Escape. Field clears. Cursor remains in the field. Type again immediately — new characters appear (no re-click required).
Gap 6 — OS drag-drop: Drag a file from Finder/Explorer over the browser window. Overlay appears. Release the file. Upload begins (progress visible or toast appears).
Automated gate:
`cd frontend && npm run test -- --run` — exits 0, zero failures, no skipped tests regressed.
</verification>
<success_criteria>
- All 6 UAT gaps confirmed closed by manual re-run of the 6 scenarios above
- `npm run test -- --run` exits 0 with zero failures across the full suite (baseline: 211 passing)
- Five production files modified with surgical changes only — no refactors, no feature additions
- Three new test files committed with passing tests covering each gap
- `grep -c "Loading" frontend/src/components/ui/TreeItem.vue` returns 0
- `grep "showSearch" frontend/src/components/storage/StorageBrowser.vue` matches the `|| props.mode === 'cloud'` form
- `grep "routeViewRef" frontend/src/App.vue` returns empty
- `grep "requiresAdmin" frontend/src/App.vue` returns the v-else-if template branch line
- `grep "addEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vue` returns a match
- `grep "removeEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vue` returns a match
- `grep "prevent.stop" frontend/src/components/documents/SearchBar.vue` returns the escape handler line
</success_criteria>
<output>
Create `/Users/nik/Documents/Progamming/document_scanner/.planning/phases/10-ux-interaction/10-13-SUMMARY.md` when done.
</output>
.planning/phases/10-ux-interaction/10-13-SUMMARY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-13-SUMMARY.md
View File
.planning/phases/10-ux-interaction/10-CONTEXT.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-CONTEXT.md
View File
.planning/phases/10-ux-interaction/10-DISCUSSION-LOG.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-DISCUSSION-LOG.md
View File
.planning/phases/10-ux-interaction/10-PATTERNS.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-PATTERNS.md
View File
.planning/phases/10-ux-interaction/10-RESEARCH.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-RESEARCH.md
View File
.planning/phases/10-ux-interaction/10-REVIEW.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-REVIEW.md
View File
.planning/phases/10-ux-interaction/10-SECURITY.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-SECURITY.md
View File
.planning/phases/10-ux-interaction/10-UAT.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-UAT.md
View File
.planning/phases/10-ux-interaction/10-VALIDATION.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-VALIDATION.md
View File
.planning/phases/10-ux-interaction/10-VERIFICATION.md → .planning/milestones/v0.2-phases/10-ux-interaction/10-VERIFICATION.md
View File
.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-01-PLAN.md
+42
View File
@@ -0,0 +1,42 @@
---
phase: 11-visual-design-responsive-layout-cleanup
plan: 1
type: execute
wave: 0
depends_on: [10-complete]
requirements: [PERF-02]
files_modified:
- frontend/vite.config.js
- .planning/phases/11-visual-design-responsive-layout-cleanup/11-RESEARCH.md
- .planning/perf/phase11-baseline.html
- .planning/perf/phase11-baseline-summary.md
autonomous: true
---
# Plan 11-01 — Bundle Baseline & UI Audit
## Objective
Capture the Phase 11 pre-optimization bundle baseline before any lazy-loading or visual cleanup begins, then record a targeted audit of the visual/responsive issues Phase 11 will address.
## Tasks
1. Wire existing `rollup-plugin-visualizer` into `frontend/vite.config.js` behind an opt-in environment flag such as `ANALYZE=true`. The dependency already exists in `frontend/package.json`.
2. Run a production build with analysis enabled and write the baseline report to `.planning/perf/phase11-baseline.html`.
3. Add `.planning/perf/phase11-baseline-summary.md` with bundle size, largest chunks, route/component observations, and the exact command used.
4. Update `11-RESEARCH.md` if execution discovers facts that differ from the refresh research.
5. Audit the frontend for Phase 11 targets:
- synchronous non-critical route imports
- responsive sidebar/admin sidebar gaps
- tables or grids that overflow below `sm`/`md`
- modal overflow below 640px
- inconsistent form, hover, focus, active, spacing, and typography patterns
- unreferenced files and imports
## Acceptance Criteria
- Baseline bundle report exists before any Phase 11 optimization commits.
- `vite.config.js` does not generate analyzer output unless explicitly requested.
- `11-RESEARCH.md` remains accurate after the baseline build.
- Audit notes are concrete enough that plans 11-02 through 11-06 can execute without rediscovering scope.
- `cd frontend && npm run build` succeeds with and without analysis enabled.
.planning/phases/11-visual-design-responsive-layout-cleanup/11-01-SUMMARY.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-01-SUMMARY.md
View File
.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-02-PLAN.md
+43
View File
@@ -0,0 +1,43 @@
---
phase: 11-visual-design-responsive-layout-cleanup
plan: 2
type: execute
wave: 1
depends_on: [11-01]
requirements: [PERF-03]
files_modified:
- frontend/src/router/index.js
- frontend/src/router/__tests__/router.guard.test.js
autonomous: true
---
# Plan 11-02 — Lazy-Load Non-Critical Routes
## Objective
Satisfy PERF-03 by lazy-loading every route component that is not needed for the initial render, while preserving auth/admin guard behavior.
## Tasks
1. Keep `FileManagerView` synchronous for `/` as the critical first authenticated surface unless the baseline report shows a strong reason to split it. Document this in `router/index.js` near the import.
2. Replace synchronous imports in `frontend/src/router/index.js` for non-initial routes:
- `TopicsView`
- `DocumentView`
- `SettingsView`
- `CloudStorageView`
- `CloudFolderView`
3. Keep `/folders/:folderId` on the same `FileManagerView` component for behavior parity with `/`; it is already in the initial chunk because `/` uses the same component.
4. Preserve existing lazy auth/admin/shared route imports.
5. Extend router tests so guard behavior is verified with lazy route components:
- non-admin cannot enter `/admin/*`
- admin redirects away from non-admin routes
- refresh-before-guard still runs when access token is absent
- `/topics`, `/document/:id`, `/settings`, `/cloud`, and `/cloud/:provider/:folderId` still resolve
6. Build once and confirm route chunks are emitted.
## Acceptance Criteria
- `rg "import .*View" frontend/src/router/index.js` only returns `FileManagerView` unless a new initial-render route is explicitly justified.
- Admin child routes remain lazy-loaded.
- Router guard tests pass.
- `cd frontend && npm run build` succeeds and emits split route chunks.
.planning/phases/11-visual-design-responsive-layout-cleanup/11-02-SUMMARY.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-02-SUMMARY.md
View File
.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-03-PLAN.md
+52
View File
@@ -0,0 +1,52 @@
---
phase: 11-visual-design-responsive-layout-cleanup
plan: 3
type: execute
wave: 2
depends_on: [11-02]
requirements: [RESP-01, RESP-02, RESP-03, RESP-05]
files_modified:
- frontend/src/App.vue
- frontend/src/layouts/AdminLayout.vue
- frontend/src/components/layout/AppSidebar.vue
- frontend/src/components/admin/AdminSidebar.vue
- frontend/src/components/storage/StorageBrowser.vue
- frontend/src/__tests__/keyboard.test.js
- frontend/src/components/storage/__tests__/StorageBrowser.skeleton.test.js
autonomous: true
---
# Plan 11-03 — Responsive Shells & Storage Rows
## Objective
Make both user and admin layouts usable below `lg`, and make storage rows fit smaller viewports without losing core actions.
## Tasks
1. Use layout-local drawer refs, not a new Pinia store:
- `App.vue` owns user drawer state.
- `AdminLayout.vue` owns admin drawer state.
- Watch route changes in each layout root and close the drawer after navigation.
- Do not put drawer state in `AppSidebar.vue` or `AdminSidebar.vue`.
2. Add a mobile-only header with a hamburger button for the user layout.
3. Hide `AppSidebar` below `lg`; open it in a slide-in overlay drawer with backdrop tap, route-change close, and `translate-x-0` / `-translate-x-full` transition.
4. Apply the same responsive shell behavior to `AdminLayout` and `AdminSidebar`.
5. Update `StorageBrowser` row/grid classes so:
- Size column hides below `md`
- Modified column hides below `sm`
- icon, name, and actions remain visible
- grid templates do not reserve hidden column widths on mobile
6. Ensure inline icon action buttons have at least `36px` touch targets below `md`.
7. Add or update tests for drawer open/close, route-change close, admin drawer behavior, responsive column classes, and touch target classes.
8. Verify with browser screenshots or Playwright at 375px, 768px, 1024px, and desktop width.
## Acceptance Criteria
- User sidebar is hidden below 1024px and accessible through a hamburger drawer.
- Admin sidebar has matching mobile behavior.
- Drawer closes on backdrop tap and navigation tap.
- Storage rows satisfy RESP-02 without horizontal overflow at 375px.
- Icon actions satisfy RESP-03.
- Drawer state is owned only by `App.vue` and `AdminLayout.vue`.
- Frontend tests and build pass.
.planning/phases/11-visual-design-responsive-layout-cleanup/11-03-SUMMARY.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-03-SUMMARY.md
View File
.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-04-PLAN.md
+40
View File
@@ -0,0 +1,40 @@
---
phase: 11-visual-design-responsive-layout-cleanup
plan: 4
type: execute
wave: 3
depends_on: [11-03]
requirements: [VISUAL-02, RESP-04]
files_modified:
- frontend/tailwind.config.js
- frontend/src/components/**/*.vue
- frontend/src/views/**/*.vue
autonomous: true
---
# Plan 11-04 — Forms Baseline & Mobile-Safe Modals
## Objective
Normalize form controls through `@tailwindcss/forms` and make every modal scroll safely on mobile viewports.
## Tasks
1. Confirm `@tailwindcss/forms` remains installed and active in `tailwind.config.js`; it is already wired today, so this should be a verification step unless execution finds drift.
2. Audit inputs, selects, textareas, checkboxes, and radio buttons for conflicting per-component browser-reset styles.
3. Normalize form classes to the smallest consistent Tailwind pattern already used by the app.
4. Update modal shells so content below 640px is scrollable and never exceeds viewport height:
- `ShareModal.vue`: centered panel gets mobile `max-h` and `overflow-y-auto`.
- `CloudCredentialModal.vue`: tall WebDAV/Nextcloud form gets mobile `max-h` and `overflow-y-auto`.
- `FolderDeleteModal.vue`: adopt the same mobile-safe panel pattern.
- `DocumentPreviewModal.vue`: preserve full-screen preview but verify header/content sizing at narrow widths.
- any auth/account confirmation modal-like surfaces found in the audit
5. Add focused tests or DOM assertions for mobile-safe modal classes and form baseline coverage.
## Acceptance Criteria
- Forms plugin is active and relied on consistently.
- No modal content overflows a 375x667 viewport.
- No modal text or action row is clipped below 640px.
- The desktop modal appearance remains behaviorally unchanged.
- `npm run test -- --run` and `npm run build` pass.
.planning/phases/11-visual-design-responsive-layout-cleanup/11-04-SUMMARY.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-04-SUMMARY.md
View File
.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-05-PLAN.md
+46
View File
@@ -0,0 +1,46 @@
---
phase: 11-visual-design-responsive-layout-cleanup
plan: 5
type: execute
wave: 4
depends_on: [11-04]
requirements: [VISUAL-01, VISUAL-03, VISUAL-04]
files_modified:
- frontend/src/components/**/*.vue
- frontend/src/views/**/*.vue
autonomous: true
---
# Plan 11-05 — Visual Consistency Pass
## Objective
Make spacing, typography, hover, focus-visible, and active states consistent across the frontend without introducing a component-library rewrite.
## Tasks
1. Preserve legitimate data-driven inline styles:
- topic color swatches
- quota/progress widths
- Teleport dropdown coordinates
- tree indentation
2. Remove arbitrary spacing and decorative inline styles unless they are data-driven layout values with no Tailwind equivalent.
3. Normalize typography to this app scale:
- page title: `text-2xl font-semibold`
- section title: `text-lg font-semibold`
- panel/table heading: `text-sm font-semibold`
- body: `text-sm`
- caption/metadata: `text-xs`
4. Replace generic `focus:ring-*` only patterns on interactive elements with this keyboard focus convention: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-1`.
5. Ensure buttons, links, card rows, table rows, menu items, and icon actions have coherent hover and active states.
6. Avoid broad palette changes; preserve the current DocuVault identity while removing one-off visual drift.
7. Add focused tests or static checks for the agreed invariants where practical.
## Acceptance Criteria
- No unnecessary `px-[...]`, margin `style=`, or one-off typography overrides remain.
- Interactive elements have hover plus keyboard-visible focus states.
- Typography reads as one app scale, not per-component choices.
- Data-driven inline styles remain where they carry runtime values.
- Visual changes are behavior-preserving.
- Frontend tests and build pass.
.planning/phases/11-visual-design-responsive-layout-cleanup/11-05-SUMMARY.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-05-SUMMARY.md
View File
.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-06-PLAN.md
+45
View File
@@ -0,0 +1,45 @@
---
phase: 11-visual-design-responsive-layout-cleanup
plan: 6
type: execute
wave: 5
depends_on: [11-05]
requirements: [CODE-07, PERF-02]
files_modified:
- frontend/src/**/*
- .planning/perf/phase11-final.html
- .planning/perf/phase11-final-summary.md
- .planning/phases/11-visual-design-responsive-layout-cleanup/11-VERIFICATION.md
autonomous: true
---
# Plan 11-06 — Dead-Code Cleanup & Final Measurement
## Objective
Delete unreferenced frontend code and capture the final bundle report after all Phase 11 optimizations are complete.
## Tasks
1. Run dead-code searches for unreferenced components, stores, helpers, imports, and old route views.
2. Explicitly classify these known suspects before deleting or retaining:
- `frontend/src/views/AccountView.vue` (`/account` currently redirects to `/settings`)
- `frontend/src/components/admin/__tests__/AdminAiConfigTab.test.js`
- `frontend/src/components/admin/__tests__/AdminQuotasTab.test.js`
- `frontend/src/components/admin/__tests__/AdminUsersTab.test.js`
3. Confirm `HomeView.vue`, `FolderView.vue`, and `AdminView.vue` remain absent.
4. Delete files with no active route and no active import in the same commit as their references are removed.
5. Remove unused imports and stale tests that target deleted files; keep behavior tests that still protect live surfaces.
6. Run the final analyzer build and write `.planning/perf/phase11-final.html`.
7. Add `.planning/perf/phase11-final-summary.md` comparing baseline vs final bundle size, chunk count, and largest chunks.
8. Produce `11-VERIFICATION.md` mapping every Phase 11 requirement to code/test/build evidence.
## Acceptance Criteria
- CODE-07 is satisfied: no dead files, unused route components, unused stores, or unused imports remain.
- Known suspects are each documented as deleted or intentionally retained.
- Final bundle report and summary are committed under `.planning/perf/`.
- Baseline and final reports are both present.
- `cd frontend && npm run test -- --run` passes.
- `cd frontend && npm run build` passes.
- Phase 11 verification maps VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, and PERF-03 to concrete evidence.
.planning/phases/11-visual-design-responsive-layout-cleanup/11-06-SUMMARY.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-06-SUMMARY.md
View File
.planning/phases/11-visual-design-responsive-layout-cleanup/11-07-PLAN.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-07-PLAN.md
View File
.planning/phases/11-visual-design-responsive-layout-cleanup/11-07-SUMMARY.md → .planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-07-SUMMARY.md
View File

Some files were not shown because too many files have changed in this diff Show More