curo1305andClaude Sonnet 4.6
123ae5b29b
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>
23 KiB
23 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, gap_closure, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | gap_closure | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 10-ux-interaction | 13 | execute | 1 |
|
true |
|
true |
|
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.
<execution_context> @/Users/nik/.claude/get-shit-done/workflows/execute-plan.md @/Users/nik/.claude/get-shit-done/templates/summary.md </execution_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.mdFrom frontend/src/App.vue (current full state — relevant sections):
<!-- 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" />
// 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:
{
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):
<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):
<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:
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:
@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):
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):
// 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.
Task 1: Sidebar shimmer rows (TreeItem.vue) and search-at-root (StorageBrowser.vue) frontend/src/components/ui/TreeItem.vue frontend/src/components/storage/StorageBrowser.vue 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".
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).
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.
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
"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.
<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> |
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.
<success_criteria>
- All 6 UAT gaps confirmed closed by manual re-run of the 6 scenarios above
npm run test -- --runexits 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.vuereturns 0grep "showSearch" frontend/src/components/storage/StorageBrowser.vuematches the|| props.mode === 'cloud'formgrep "routeViewRef" frontend/src/App.vuereturns emptygrep "requiresAdmin" frontend/src/App.vuereturns the v-else-if template branch linegrep "addEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vuereturns a matchgrep "removeEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vuereturns a matchgrep "prevent.stop" frontend/src/components/documents/SearchBar.vuereturns the escape handler line </success_criteria>