diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 56e8006..d27a967 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -26,7 +26,7 @@ Before any phase is marked complete: | 12 | 6/6 | Complete | 2026-06-21 | | 13 | 11/11 | Complete | 2026-06-23 | | 14 | 9/9 | Complete | 2026-06-23 | -| 14.1 | 2/5 | In Progress| | +| 14.1 | 3/5 | In Progress| | | 14.2 | Cross-Codebase Review and Cleanup | Cross-reference backend/frontend code, remove duplication and dead code, consolidate shared paths, and fix inefficiencies without behavior changes | Cross-cutting quality gates | | 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 | @@ -141,14 +141,14 @@ Plans: **Goal:** Cloud files opened, viewed, downloaded, analyzed, and displayed in results use the same user-facing behavior as local files, while preserving provider ownership, cache boundaries, authorization, and no-provider-mutation guarantees. **Requirements:** CLOUD-02, ANALYZE-01, ANALYZE-02, ANALYZE-03, ANALYZE-04, ANALYZE-05, ANALYZE-06, ANALYZE-07, CACHE-03, CACHE-04, CACHE-05 **Depends on:** Phase 14 -**Plans:** 2/5 plans executed +**Plans:** 3/5 plans executed **Execution waves:** Wave 1: 14.1-01 (RED tests); Wave 2: 14.1-02 after 01 (backend detail/force/retry); Wave 3: 14.1-03 after 01-02 (shared detail surface + cloud route/view); Wave 4: 14.1-04 after 01-03 (browser row parity + cloud row navigation); Wave 5: 14.1-05 after 01-04 (gates, security, docs, version, commit). Plans: - [x] 14.1-01-PLAN.md — RED backend + frontend parity tests (cloud detail endpoint, force re-analyze, single-item retry, route + row parity). - [x] 14.1-02-PLAN.md — Backend cloud detail endpoint (CloudItemDetailOut + resolve_owned_cloud_item_detail), force re-analyze flag, single-item retry-job creation. -- [ ] 14.1-03-PLAN.md — Shared DocumentDetailSurface extraction, DocumentView refactor (Re-analyze copy), CloudDetailView + cloud-file-detail route + getCloudItemDetail. +- [x] 14.1-03-PLAN.md — Shared DocumentDetailSurface extraction, DocumentView refactor (Re-analyze copy), CloudDetailView + cloud-file-detail route + getCloudItemDetail. - [ ] 14.1-04-PLAN.md — Browse row topics/analysis_status/stale, StorageBrowser row parity via store translator, cloud row click → cloud detail route (no auto preview/download). - [ ] 14.1-05-PLAN.md — Full test suites, security gate, dependency/secret audits, CLAUDE.md/README updates, version bump, atomic commit. diff --git a/.planning/STATE.md b/.planning/STATE.md index 3b1f74e..5c35ff1 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -6,14 +6,14 @@ current_phase: 14.1 current_phase_name: cloud-local-file-parity-hardening status: executing stopped_at: Phase 14.1 UI-SPEC approved -last_updated: "2026-06-26T20:03:08.999Z" +last_updated: "2026-06-26T20:14:05.841Z" last_activity: 2026-06-26 last_activity_desc: Phase 14.1 execution started progress: total_phases: 8 completed_phases: 4 total_plans: 35 - completed_plans: 32 + completed_plans: 33 percent: 50 --- @@ -26,7 +26,7 @@ progress: ## Current Position Phase: 14.1 (cloud-local-file-parity-hardening) — EXECUTING -Plan: 3 of 5 +Plan: 4 of 5 Status: Ready to execute Last activity: 2026-06-26 — Phase 14.1 execution started @@ -75,6 +75,7 @@ Last activity: 2026-06-26 — Phase 14.1 execution started | Phase 14 P09 | 11m | 2 tasks | 9 files | | Phase 14.1 P01 | 13m | 2 tasks | 4 files | | Phase 14.1 P02 | 18m | 2 tasks | 5 files | +| Phase 14.1 P03 | 5m | 2 tasks | 6 files | ## Accumulated Context @@ -127,7 +128,7 @@ _Updated at each phase transition._ | Field | Value | |---|---| -| Last session | 2026-06-26T20:03:08.994Z | +| Last session | 2026-06-26T20:13:33.570Z | | Next action | Plan 14.1 | | Pending decisions | None | | Resume file | .planning/phases/14.1-cloud-local-file-parity-hardening/14.1-UI-SPEC.md | @@ -176,3 +177,6 @@ _Updated at each phase transition._ - [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 - [Phase ?]: Phase 14 version bump: 0.3.0→0.4.0 +- [Phase ?]: DocumentDetailSurface is shared detail surface for local+cloud +- [Phase ?]: cloud-file-detail route uses /item/ path segment to disambiguate from cloud-folder wildcard +- [Phase ?]: previewState inferred from content_type (empty capabilities={}; live resolution requires credentials per Plan 02) diff --git a/.planning/phases/14.1-cloud-local-file-parity-hardening/14.1-03-SUMMARY.md b/.planning/phases/14.1-cloud-local-file-parity-hardening/14.1-03-SUMMARY.md new file mode 100644 index 0000000..35ac53e --- /dev/null +++ b/.planning/phases/14.1-cloud-local-file-parity-hardening/14.1-03-SUMMARY.md @@ -0,0 +1,221 @@ +--- +phase: 14.1-cloud-local-file-parity-hardening +plan: "03" +subsystem: cloud-detail-frontend +status: complete +tags: [frontend, shared-surface, cloud-detail, force-reanalyze, parity, route] +requirements: [CLOUD-02, ANALYZE-01, ANALYZE-05, ANALYZE-06, CACHE-03] + +dependency_graph: + requires: + - 14.1-01 (RED tests — CloudDetailParity.test.js must pass) + - 14.1-02 (backend cloud detail endpoint + force field + retry route) + provides: + - frontend/src/components/storage/DocumentDetailSurface.vue + - frontend/src/views/CloudDetailView.vue + - frontend/src/router/index.js (cloud-file-detail route added) + - frontend/src/api/cloud.js (getCloudItemDetail added) + - frontend/src/stores/cloudConnections.js (force param + fetchCloudItemDetail) + affects: + - frontend/src/components/storage/StorageBrowser.vue (Plan 04 target — Re-analyze in rows) + - frontend/src/views/CloudFolderView.vue (Plan 04 target — row click navigates to cloud-file-detail) + +tech_stack: + added: [] + patterns: + - Shared detail surface pattern (DocumentDetailSurface as layout owner; DocumentView + CloudDetailView as thin data providers) + - Single analysis action slot (swaps Analyze/Re-analyze/Retry by kind — never accumulates) + - Opaque provider itemId in route params — encodeURIComponent in API, never decoded/split in frontend + - Force re-analyze with confirmation dialog (Copywriting Contract destructive copy) + - Preview unavailable keeps Download active, no auto-download (D-14) + +key_files: + created: + - frontend/src/components/storage/DocumentDetailSurface.vue + - frontend/src/views/CloudDetailView.vue + modified: + - frontend/src/views/DocumentView.vue + - frontend/src/router/index.js + - frontend/src/api/cloud.js + - frontend/src/stores/cloudConnections.js + +decisions: + - DocumentDetailSurface is a presentational smart component with named slots for secondary-actions, topics-actions, topics-error, suggestions, and secondary-controls + - Topics prop accepts both string arrays (cloud) and object arrays with {name, color} (local) — normalized in computed + - DocumentView analysis action is always 'reanalyze' kind (local files are always analyzed); busy flag controlled by classifying ref + - Cloud route path uses /item/ segment before itemId to disambiguate from /cloud-folder /:folderId(.*) wildcard + - cloudConnections.js imports cloudApi (cloud.js) separately from api (client.js) for getCloudItemDetail — no local redefinition + - Re-analyze confirmation modal shown before any force=true enqueue; cancel keeps existing analysis data visible + +metrics: + duration: "5m" + completed_date: "2026-06-26" + tasks_completed: 2 + files_created: 2 + files_modified: 4 + frontend_tests_passing: 488 + test_suite_delta: +0 new failures (1 pre-existing Plan 01 RED test for Plan 04 target) +--- + +# Phase 14.1 Plan 03: Shared Document Detail Surface + Cloud Detail Route Summary + +Extract a shared `DocumentDetailSurface.vue` from `DocumentView.vue`, refactor local document detail to a thin data provider using it, build `CloudDetailView.vue` backed by the Plan 02 `getCloudItemDetail` endpoint, add the named `cloud-file-detail` route, wire force re-analyze with confirmation, and ensure unsupported preview keeps Download active without auto-downloading. + +## Tasks Completed + +### Task 1: Extract DocumentDetailSurface.vue + refactor DocumentView.vue (Re-analyze copy) + +**`frontend/src/components/storage/DocumentDetailSurface.vue`** (new, 190 lines): + +Created as a presentational smart component owning the shared detail layout for both local and cloud files. Implements the UI-SPEC Detail Layout Contract section order: + +1. Back navigation (slot — overridable) +2. Header block: title (24px semibold, break-all), metadata line (12–14px muted), cloud provider chip + location (subtle, providerColor/providerBg from formatters), primary action cluster +3. Status and source notice area (stale amber badge, preview unavailable notice, working status, cloud source footnote) +4. Topics section (TopicBadge + "No topics assigned yet." empty copy, topics-actions slot) +5. Extracted text (pre block with "No analysis yet / Analyze this file…" Copywriting Contract empty state) +6. Secondary controls slot + +Props: `title`, `metadataLine`, `source` (`{provider, location, isStale, statusLabel}`), `topics` (string[] or `{name, color}[]`), `analysisStatus`, `extractedText`, `previewState` (`{supported, reason, openLabel}`), `downloadState` (`{supported}`), `analysisAction` (`{kind: 'analyze'|'reanalyze'|'retry', busy}`). + +Emits: `back`, `preview`, `download`, `analyze`, `reanalyze`, `retry-analysis`. + +Single analysis action slot: exactly one of Analyze/Re-analyze/Retry buttons renders at a time — swaps by `analysisAction.kind` (UI-SPEC Re-Analyze contract). Imports exclusively from `utils/formatters.js` (no local redefinitions). + +**`frontend/src/views/DocumentView.vue`** (refactored): + +Reduced to thin data provider. Renders `DocumentDetailSurface` with local document data. Injects secondary-actions (Delete), topics-actions (Suggest Topics), topics-error (classify error), and suggestions panel via named slots. Visible button label changed from "Re-classify" to "Re-analyze" (internal `classifyDocument` API call preserved per D-09). + +**Verification:** +- CloudDetailParity Re-classify regression test passes ✓ +- DocumentView section rendering test passes ✓ +- No rendered "Re-classify" in either file ✓ +- `grep -c "from '../../utils/formatters"` → 1 ✓ + +**Commit:** 825a7b5 + +### Task 2: Cloud detail route + CloudDetailView.vue + getCloudItemDetail API + store force/reanalyze wiring + +**`frontend/src/router/index.js`:** + +Added named route `cloud-file-detail` at `/cloud/:connectionId/item/:itemId(.*)` with `requiresAuth: true`. Declared before the `cloud-folder` route (which has `/:folderId(.*)`) to prevent wildcard capture. The distinct `/item/` segment disambiguates. `itemId` is opaque — Vue Router handles URI encoding (T-14.1-08). + +**`frontend/src/api/cloud.js`:** + +Added `getCloudItemDetail(connectionId, itemId)` calling `GET /api/cloud/connections/${connectionId}/items/${encodeURIComponent(itemId)}/detail` via the `request` helper (T-14.1-03/T-14.1-06: credential-free, zero bytes). + +**`frontend/src/views/CloudDetailView.vue`** (new, 316 lines): + +Thin data-provider view. Reads `connectionId` + `itemId` from route params (never split/decoded). Calls `cloudApi.getCloudItemDetail` on mount. Maps response to `DocumentDetailSurface` props: + +- `source.isStale` derived from `is_stale` or `analysis_status === 'stale'` (D-07) +- `source.statusLabel` via `cloudStore.translateAnalysisStatus` — single translator, no local translation (D-06) +- `analysisAction.kind` derived from `analysis_status`: `analyze` (none/pending), `reanalyze` (indexed/stale/current), `retry` (failed/partial), `null` (unsupported) +- `previewState.supported` inferred from `content_type` (PDF/image → true; others → false with reason) +- `downloadState.supported: true` (authorized download always available) + +Event handlers: +- `preview` → `cloudApi.previewCloudFile`; on `unsupported_preview`, surfaces reason inline — never auto-downloads (D-14) +- `download` → `cloudApi.downloadCloudFile` +- `analyze` → `cloudStore.enqueueAnalysis({ scope: 'file', provider_item_ids: [itemId] })` +- `reanalyze` → shows confirmation modal (Copywriting Contract: "Re-analyze this file? Existing extracted text and topics stay visible until the new analysis finishes.") → on confirm, `enqueueAnalysis({ force: true })` +- `retry-analysis` → `enqueueAnalysis({ force: true })` (D-12 single-item retry path) + +**`frontend/src/stores/cloudConnections.js`:** + +Extended `enqueueAnalysis` to accept and forward `force` param (D-11). Added `fetchCloudItemDetail` action calling `cloudApi.getCloudItemDetail`. Imports `cloudApi` from `../api/cloud.js` separately from `api` (client.js barrel). + +**Verification:** +- All 8 `CloudDetailParity.test.js` tests pass ✓ +- Full suite: 488 passed, 1 pre-existing RED failure (Plan 04 target) ✓ + +**Commit:** 48afb8b + +## Verification Results + +### Plan verification (npx vitest run src/views/__tests__/CloudDetailParity.test.js) + +``` +Test Files 1 passed (1) +Tests 8 passed (8) +``` + +All 8 RED tests from Plan 01 now green: +- Route includes cloud-file-detail ✓ +- Route resolves with connectionId + itemId params ✓ +- Local /document/:id route preserved ✓ +- Paired route parity (both routes coexist) ✓ +- Cloud row navigation prerequisite met ✓ +- DocumentView does not contain Re-classify ✓ +- DocumentView renders extracted-text and topics ✓ +- Re-analyze copy prerequisite met ✓ + +### Full suite (npx vitest run) + +``` +Test Files 1 failed | 51 passed (52) +Tests 1 failed | 488 passed (489) +``` + +1 pre-existing RED failure: `StorageBrowser.parity.test.js > Cloud indexed file shows Re-analyze (not Re-classify)` — targeted by Plan 04 which adds Re-analyze copy to cloud rows in StorageBrowser. This failure existed before Plan 03 and is unaffected. + +### Acceptance criteria + +- `grep -c "from '../../utils/formatters" frontend/src/components/storage/DocumentDetailSurface.vue` → 1 ✓ +- `grep -c 'DocumentDetailSurface' frontend/src/views/DocumentView.vue` → 3 ✓ +- `grep -c 'Re-classify' frontend/src/views/DocumentView.vue frontend/src/components/storage/DocumentDetailSurface.vue` → 0 in templates (1 in DocumentView comment only — confirmed not rendered) ✓ +- `grep -c 'Re-analyze' frontend/src/components/storage/DocumentDetailSurface.vue` → 3 ✓ +- Single analysis action slot confirmed (v-if/v-else-if chain, no simultaneous buttons) ✓ +- `grep -c 'cloud-file-detail' frontend/src/router/index.js` → 2 (1 in comment, 1 in route name); CloudDetailView referenced ✓ +- `grep -c 'getCloudItemDetail' frontend/src/api/cloud.js` → 1; uses encodeURIComponent ✓ +- `grep -c 'DocumentDetailSurface' frontend/src/views/CloudDetailView.vue` → 4 ✓ +- Force wired: `grep -nE 'force' frontend/src/views/CloudDetailView.vue` → force: true in confirmReanalyze + handleRetry; `grep -nE 'force' frontend/src/stores/cloudConnections.js` → forwarded via spread ✓ +- `grep -c 'Preview unavailable' frontend/src/views/CloudDetailView.vue` → 4 ✓ +- `grep -c 'function translateAnalysisStatus' frontend/src/stores/cloudConnections.js` → 1; CloudDetailView has no local translator ✓ +- CloudDetailParity.test.js passes (8/8) ✓ + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 2 - Missing critical functionality] cloudConnections.js imports client.js (api), not cloud.js** +- **Found during:** Task 2 store wiring +- **Issue:** The store's existing `import * as api from '../api/client.js'` only covers local document API. `getCloudItemDetail` lives in `cloud.js`. Adding `fetchCloudItemDetail` to the store required importing the cloud API barrel separately. +- **Fix:** Added `import * as cloudApi from '../api/cloud.js'` alongside the existing `api` import; `fetchCloudItemDetail` delegates to `cloudApi.getCloudItemDetail`. No disruption to any existing store action (all continue to use the correct `api.*` barrel). +- **Files modified:** frontend/src/stores/cloudConnections.js +- **Commit:** 48afb8b + +**2. [Rule 2 - Missing critical functionality] Preview state inferred from content_type (no live capability call)** +- **Found during:** Task 2 — mapping CloudItemDetailOut to previewState +- **Issue:** `CloudItemDetailOut.capabilities` is an empty dict (intentional Plan 02 decision — live capability resolution requires credential decryption, violating CACHE-03). The frontend must infer preview availability without a capability signal. +- **Fix:** `previewStateProps` computed in CloudDetailView infers from `content_type`: PDF and image/* → supported; all others → unsupported with a human-readable reason. This is safe because the backend preview endpoint will reject unsupported formats with a typed `unsupported_preview` response, which handlePreview catches and surfaces as a reason (D-14). +- **Files modified:** frontend/src/views/CloudDetailView.vue +- **Commit:** 48afb8b + +## Known Stubs + +None — all fields come from the backend CloudItemDetailOut response. The `capabilities={}` empty dict from the backend is an intentional architectural decision (documented in Plan 02 SUMMARY, Deviation 1). + +## Threat Flags + +| Flag | File | Description | +|------|------|-------------| +| T-14.1-07 (mitigated) | CloudDetailView.vue | View renders only allowlisted CloudItemDetailOut fields; template contains no provider URL, credential, object_key binding; provider chip uses only `item.provider` (slug) via providerColor/providerBg/providerLabel from formatters | +| T-14.1-08 (mitigated) | router/index.js + cloud.js | itemId passed opaque throughout; encodeURIComponent applied in API call; Vue Router encodes route param; no split/decode in CloudDetailView | +| T-14.1-09 (mitigated) | CloudDetailView.vue | previewState.supported=false shows reason; Download is a separate explicit action; handlePreview never auto-downloads on unsupported; "Preview unavailable" message present (grep -c → 4) | + +## Self-Check: PASSED + +Created files exist: +- /Users/nik/Documents/Progamming/document_scanner/frontend/src/components/storage/DocumentDetailSurface.vue ✓ +- /Users/nik/Documents/Progamming/document_scanner/frontend/src/views/CloudDetailView.vue ✓ + +Modified files: +- /Users/nik/Documents/Progamming/document_scanner/frontend/src/views/DocumentView.vue ✓ +- /Users/nik/Documents/Progamming/document_scanner/frontend/src/router/index.js ✓ +- /Users/nik/Documents/Progamming/document_scanner/frontend/src/api/cloud.js ✓ +- /Users/nik/Documents/Progamming/document_scanner/frontend/src/stores/cloudConnections.js ✓ + +Commits verified: +- 825a7b5 (Task 1) present in git log ✓ +- 48afb8b (Task 2) present in git log ✓