ss-tools/specs/014-file-storage-ui/tasks.md

Tasks: File Storage Management & UI

Branch: 014-file-storage-ui | Spec: specs/014-file-storage-ui/spec.md

Phase 1: Setup

Goal: Initialize backend plugin structure and frontend route scaffolding.

• T001 Create storage plugin directory and __init__.py in backend/src/plugins/storage/
• T002 Create storage models file backend/src/models/storage.py with StorageConfig and StoredFile Pydantic models
• T003 Create empty storage route handler backend/src/api/routes/storage.py and register in backend/src/api/routes/__init__.py
• T004 Create frontend storage route directory frontend/src/routes/tools/storage/ and empty +page.svelte
• T005 Create frontend service frontend/src/services/storageService.js stub

Phase 2: Foundational

Goal: Implement core backend logic for storage management, configuration, and security.

• T006 Implement StoragePlugin class in backend/src/plugins/storage/plugin.py inheriting from PluginBase
• T007 Implement get_storage_root() method in StoragePlugin with default path logic (../ss-tools-storage)
• T008 Implement ensure_directories() method to create backups/ and repositories/ subfolders on init
• T009 Implement path traversal protection helper validate_path(path) in StoragePlugin
• T010 Implement list_files(category) method in StoragePlugin returning StoredFile objects
• T011 Implement save_file(file, category) method in StoragePlugin handling uploads
• T012 Implement delete_file(category, filename) method in StoragePlugin
• T013 Implement get_file_path(category, filename) method in StoragePlugin for downloads
• T014 Register StoragePlugin in backend/src/core/plugin_loader.py (if manual registration needed)

Phase 3: User Story 1 - File Management Dashboard (Priority: P1)

Goal: Enable users to list, upload, download, and delete files via Web UI.

Backend Endpoints

• T015 [US1] Implement GET /api/storage/files endpoint in backend/src/api/routes/storage.py using StoragePlugin.list_files
• T016 [US1] Implement POST /api/storage/upload endpoint in backend/src/api/routes/storage.py using StoragePlugin.save_file
• T017 [US1] Implement DELETE /api/storage/files/{category}/{filename} endpoint in backend/src/api/routes/storage.py
• T018 [US1] Implement GET /api/storage/download/{category}/{filename} endpoint in backend/src/api/routes/storage.py

Frontend Implementation

• T019 [US1] Implement listFiles, uploadFile, deleteFile, downloadFileUrl in frontend/src/services/storageService.js
• T020 [US1] Create frontend/src/components/storage/FileList.svelte to display files in a table with metadata
• T021 [US1] Create frontend/src/components/storage/FileUpload.svelte with category selection and drag-drop support
• T022 [US1] Implement main logic in frontend/src/routes/tools/storage/+page.svelte to fetch files and handle tabs (Backups vs Repositories)
• T023 [US1] Integrate FileList and FileUpload components into +page.svelte

Phase 4: User Story 2 - Storage Location Configuration (Priority: P2)

Goal: Allow administrators to configure the storage root path via Settings.

Backend

• T024 [US2] Add storage_path field to main configuration model in backend/src/core/config_models.py (if not using separate storage config)
• T025 [US2] Implement GET /api/settings/storage and PUT /api/settings/storage endpoints in backend/src/api/routes/settings.py (or storage.py)
• T026 [US2] Update StoragePlugin to read root path from global configuration instead of hardcoded default
• T027 [US2] Add validation logic to PUT endpoint to ensure new path is writable

Frontend

• T028 [US2] Add getStorageConfig and updateStorageConfig to frontend/src/services/storageService.js
• T029 [US2] Create configuration section in frontend/src/routes/settings/+page.svelte (or dedicated Storage Settings component)
• T030 [US2] Implement form to update storage path with validation feedback
• T031 [US2] Add configuration fields for directory structure and filename patterns in backend/src/models/storage.py and frontend/src/routes/settings/+page.svelte
• T032 [US2] Implement logic in StoragePlugin to resolve dynamic paths based on configured patterns

Phase 5: Polish & Cross-Cutting

Goal: Finalize UI/UX and ensure robustness.

• T033 Add link to "File Storage" in main navigation frontend/src/components/Navbar.svelte
• T034 Add error handling toasts for failed uploads or file operations
• T035 Verify large file upload support (50MB+) in Nginx/FastAPI config if applicable
• T036 Add confirmation modal for file deletion

Phase 6: Folder Structure Support (Refactor)

Goal: Enable hierarchical navigation, nested file management, and downloading.

• T037 Refactor StoragePlugin.list_files in backend/src/plugins/storage/plugin.py to accept subpath and return directories/files
• T038 Refactor StoragePlugin methods (save_file, delete_file, get_file_path) to support nested paths
• T039 Update backend endpoints in backend/src/api/routes/storage.py (GET /files, POST /upload, DELETE /files, GET /download) to accept path parameter
• T040 Update frontend/src/services/storageService.js to pass path argument in all API calls
• T041 Update frontend/src/components/storage/FileList.svelte to display folder icons, handle navigation events, and show breadcrumbs
• T042 Update frontend/src/components/storage/FileUpload.svelte to upload to the currently active directory
• T043 Update frontend/src/routes/tools/storage/+page.svelte to manage current path state and handle navigation logic

Dependencies

1. Phase 1 (Setup): No dependencies.
2. Phase 2 (Foundational): Depends on Phase 1.
3. Phase 3 (US1): Depends on Phase 2.
4. Phase 4 (US2): Depends on Phase 2. Can run parallel to Phase 3.
5. Phase 5 (Polish): Depends on Phase 3 and 4.
6. Phase 6 (Refactor): Depends on Phase 3.

Parallel Execution Examples

• Backend/Frontend Split: T015-T018 (Backend Endpoints) can be developed in parallel with T020-T021 (Frontend Components) using mock data.
• Story Split: US1 (File Management) and US2 (Configuration) are largely independent after Phase 2 is complete.

Implementation Strategy

1. MVP: Complete Phases 1, 2, and 3. This delivers a working file manager with a default storage location.
2. Full Feature: Complete Phase 4 to allow path configuration.
3. Polish: Complete Phase 5 for better UX.