@forloop-cc/forloop-opencode-plugin-planner 2.2.1

package/docs/file-management/FILE_UPLOAD_ENHANCEMENT.md

@@ -0,0 +1,431 @@
+# File Upload Enhancement - Implementation Summary
+
+## Changes Made
+
+This document summarizes the implementation of S3 folder organization and doc_folder linking for file uploads.
+
+---
+
+## New Parameters Added
+
+### `forloopFileUpload` Tool (Plugin)
+
+**File:** `forloop-opencode-plugin-planner/plugins/tools/file-tools.ts`
+
+```typescript
+args: {
+  filePath: string;        // Local file path (required)
+  sprintId: number;        // Target sprint (required)
+  description?: string;    // File description (optional)
+  folder?: string;         // S3 folder path (NEW - optional)
+  storyId?: number;        // Link to story (NEW - optional)
+}
+```
+
+---
+
+### API Client `completeUpload` Method
+
+**File:** `forloop-opencode-plugin-planner/plugins/capabilities/api-client.ts`
+
+```typescript
+async completeUpload(data: {
+  sprintId: number;
+  fileName: string;
+  originalName: string;
+  fileType: string;
+  size: number;
+  folder?: string;     // NEW - optional
+  storyId?: number;    // NEW - optional
+  x?: number;
+  y?: number;
+}): Promise<any>
+```
+
+---
+
+### Server Controller Endpoints
+
+**File:** `server_lambda/src/controllers/uploadController.ts`
+
+#### 1. `createPresignedUpload`
+```typescript
+const { sprintId, contentType, originalName, folder } = req.body;
+const key = folder 
+  ? `sprint/${sprintId}/${folder}/${fileName}`
+  : `sprint/${sprintId}/${fileName}`;
+```
+
+#### 2. `completeUpload`
+```typescript
+const { sprintId, x, y, storyId, fileName, originalName, fileType, size, folder } = req.body;
+const key = folder 
+  ? `sprint/${sprintId}/${folder}/${fileName}`
+  : `sprint/${sprintId}/${fileName}`;
+```
+
+#### 3. `uploadCanvasFile`
+```typescript
+const { sprintId, x, y, storyId, folder } = req.body;
+const key = folder 
+  ? `sprint/${sprintId}/${folder}/${fileName}`
+  : `sprint/${sprintId}/${fileName}`;
+```
+
+---
+
+## Usage Examples
+
+### Example 1: Upload with S3 Folder Organization
+
+Upload planning artifacts to organized S3 folders:
+
+```bash
+# Upload sprint plan to project/plans folder
+forloopFileUpload \
+  --filePath ~/.forloop/plan/plan-14-20260410-093015.md \
+  --sprintId 14 \
+  --folder project/plans \
+  --description "Sprint 14 plan document"
+
+# Upload knowledge to project/knowledge folder
+forloopFileUpload \
+  --filePath ~/.forloop/knowledge/knowledge-auth-20260410-093015.md \
+  --sprintId 14 \
+  --folder project/knowledge \
+  --description "Auth system knowledge"
+
+# Upload task file to project/tasks folder
+forloopFileUpload \
+  --filePath ~/.forloop/task/task-14-20260410-100000.md \
+  --sprintId 14 \
+  --folder project/tasks \
+  --description "Sprint 14 task list"
+```
+
+**Result - S3 Structure:**
+```
+s3://bucket/sprint/14/
+├── project/
+│   ├── plans/
+│   │   └── plan-14-20260410-093015.md
+│   ├── knowledge/
+│   │   └── knowledge-auth-20260410-093015.md
+│   └── tasks/
+│       └── task-14-20260410-100000.md
+```
+
+---
+
+### Example 2: Upload with doc_folder Linking
+
+Link files to doc_folder stories for UI organization:
+
+```bash
+# Step 1: Create a doc_folder story
+forloopDocFolder \
+  --sprintId 14 \
+  --title "Project Artifacts" \
+  --description "Planning documents and knowledge" \
+  --permissions team
+
+# Output:
+# ✅ Document folder created!
+# **#101**: Project Artifacts
+# **Type**: doc_folder
+
+# Step 2: Upload file and link to doc_folder (Story #101)
+forloopFileUpload \
+  --filePath ~/.forloop/plan/plan-14.md \
+  --sprintId 14 \
+  --storyId 101 \
+  --description "Sprint plan linked to Project Artifacts"
+```
+
+**Result:**
+- **S3 Path:** `s3://bucket/sprint/14/plan-14.md` (root level)
+- **Database:** `{ storyId: 101 }` (linked to "Project Artifacts" folder)
+- **UI:** Shows under "Project Artifacts" folder in ForLoop app
+
+---
+
+### Example 3: Combined Organization (Future Use)
+
+Use both S3 folder AND doc_folder linking:
+
+```bash
+# Upload with physical folder + logical grouping
+forloopFileUpload \
+  --filePath ~/.forloop/plan/plan-14.md \
+  --sprintId 14 \
+  --folder project/plans \
+  --storyId 101 \
+  --description "Plan in S3 folder, linked to UI folder"
+```
+
+**Result:**
+- **S3 Path:** `s3://bucket/sprint/14/project/plans/plan-14.md`
+- **Database:** `{ storyId: 101 }`
+- **UI:** Shows under "Project Artifacts" folder
+
+---
+
+## Backward Compatibility
+
+### ✅ Guaranteed
+
+1. **Optional Parameters:** Both `folder` and `storyId` are optional
+2. **Default Behavior:** When not provided, files upload to `sprint/{id}/{file}` (current behavior)
+3. **Frontend Unchanged:** Existing frontend code continues to work without modifications
+4. **No Breaking Changes:** All existing API contracts remain intact
+
+### Frontend Client Impact
+
+**Frontend calls (`client/src/store/sprintStore.ts`):**
+```typescript
+// presign call - NO changes needed
+await api.post('/files/presign', {
+  sprintId,
+  contentType: file.type,
+  originalName: file.name,
+})
+
+// complete call - NO changes needed
+await api.post('/files/complete', {
+  sprintId,
+  x, y, storyId,
+  fileName: presignRes.data.fileName,
+  // ...
+})
+```
+
+Server handles missing `folder` parameter:
+```typescript
+// When folder is undefined, uses default path
+const key = folder 
+  ? `sprint/${sprintId}/${folder}/${fileName}`
+  : `sprint/${sprintId}/${fileName}`;  // ← Default (existing)
+```
+
+---
+
+## File Organization Patterns
+
+### Pattern 1: S3 Folder Only
+
+**Use Case:** S3 management, external tool access, backup organization
+
+```bash
+forloopFileUpload \
+  --filePath ./plan.md \
+  --sprintId 14 \
+  --folder project/plans
+```
+
+**S3 Console Shows:**
+```
+sprint/14/
+└── project/
+    └── plans/
+        └── user_abc123_plan.md
+```
+
+---
+
+### Pattern 2: doc_folder Only
+
+**Use Case:** In-app UI organization, grouping related files
+
+```bash
+# Create folder
+forloopDocFolder --sprintId 14 --title "Specs"
+
+# Upload and link
+forloopFileUpload \
+  --filePath ./api-spec.md \
+  --sprintId 14 \
+  --storyId 102
+```
+
+**ForLoop UI Shows:**
+```
+📁 Specs (doc_folder)
+└── 📄 api-spec.md
+```
+
+---
+
+### Pattern 3: Root Level (Default)
+
+**Use Case:** Simple files, no special organization needed
+
+```bash
+forloopFileUpload \
+  --filePath ./quick-note.md \
+  --sprintId 14 \
+  --description "Quick note"
+```
+
+**Result:**
+- **S3:** `s3://bucket/sprint/14/quick-note.md`
+- **UI:** Shows in sprint root files list
+
+---
+
+## Integration with Existing Skills
+
+### Updated Skills Documentation
+
+The following skills were updated to include `folder` parameter examples:
+
+1. **file-management/SKILL.md** - Primary documentation
+2. **knowledge-management/SKILL.md** - Example with `project/knowledge`
+3. **plan-documentation/SKILL.md** - Example with `project/plans`
+4. **task-tracking/SKILL.md** - Example with `project/tasks`
+
+### Skill Workflow Integration
+
+**Complete Sprint Planning Flow:**
+
+```bash
+# 1. Create doc_folder for organization
+forloopDocFolder \
+  --sprintId 14 \
+  --title "Sprint 14 Artifacts"
+
+# 2. Capture knowledge (knowledge-management skill)
+#    → Creates: .forloop/knowledge/knowledge-auth-*.md
+#    → Uploads to: project/knowledge/
+
+# 3. Create plan (plan-documentation skill)
+#    → Creates: .forloop/plan/plan-14-*.md
+#    → Uploads to: project/plans/
+
+# 4. Create tasks (task-tracking skill)
+#    → Creates: .forloop/task/task-14-*.md
+#    → Uploads to: project/tasks/
+#    → Links stories to sprint
+
+# Result: Organized S3 structure with all planning artifacts
+```
+
+---
+
+## Verification Checklist
+
+### Implementation
+
+- ✅ Plugin tool updated with `folder` and `storyId` parameters
+- ✅ API client updated to pass new parameters
+- ✅ Server `createPresignedUpload` handles `folder`
+- ✅ Server `completeUpload` handles `folder` and `storyId`
+- ✅ Server `uploadCanvasFile` handles `folder`
+- ✅ TypeScript compilation passes (both projects)
+
+### Documentation
+
+- ✅ file-management skill updated with examples
+- ✅ knowledge-management skill updated
+- ✅ plan-documentation skill updated
+- ✅ task-tracking skill updated
+- ✅ This summary document created
+
+---
+
+## Testing Recommendations
+
+### Manual Test Cases
+
+1. **Upload without folder (backward compatibility)**
+   ```bash
+   forloopFileUpload --filePath ./test.md --sprintId 14
+   # Should upload to: sprint/14/test.md
+   ```
+
+2. **Upload with folder**
+   ```bash
+   forloopFileUpload --filePath ./test.md --sprintId 14 --folder project
+   # Should upload to: sprint/14/project/test.md
+   ```
+
+3. **Upload with storyId**
+   ```bash
+   forloopFileUpload --filePath ./test.md --sprintId 14 --storyId 101
+   # Should upload to: sprint/14/test.md with storyId: 101
+   ```
+
+4. **Upload with folder and storyId**
+   ```bash
+   forloopFileUpload --filePath ./test.md --sprintId 14 --folder project --storyId 101
+   # Should upload to: sprint/14/project/test.md with storyId: 101
+   ```
+
+5. **Frontend upload (no changes)**
+   ```javascript
+   // Existing frontend code should continue to work
+   uploadFile(14, file, 100, 200)
+   ```
+
+---
+
+## S3 Bucket Structure Examples
+
+### Before (Flat Structure)
+```
+s3://bucket/sprint/14/
+├── user_abc123_plan.md
+├── user_def456_knowledge.md
+└── user_ghi789_task.md
+```
+
+### After (Organized with Folders)
+```
+s3://bucket/sprint/14/
+├── project/
+│   ├── plans/
+│   │   └── user_abc123_plan.md
+│   ├── knowledge/
+│   │   └── user_def456_knowledge.md
+│   └── tasks/
+│       └── user_ghi789_task.md
+└── meetings/
+    └── recording_20260410.mp4
+```
+
+---
+
+## Migration Path
+
+### For Existing Files
+
+**No migration needed** - existing files remain at `sprint/{id}/{file}`. New files can use the `folder` parameter for organization.
+
+### For New Projects
+
+Recommended folder structure for `.forloop/` artifacts:
+
+```
+S3: sprint/{id}/
+├── project/
+│   ├── plans/         ← Sprint plan documents
+│   ├── knowledge/     ← Captured knowledge files
+│   └── tasks/         ← Task list files
+└── meetings/
+    ├── {meetingId}/   ← Meeting recordings
+    │   └── {timestamp}/
+    └── summaries/     ← Meeting summaries
+```
+
+---
+
+## Summary
+
+This implementation adds flexible file organization to ForLoop:
+
+1. **Physical S3 folders** via `folder` parameter
+2. **Logical UI grouping** via `storyId` parameter (linking to doc_folder)
+3. **Full backward compatibility** - all parameters optional
+4. **Updated skills** to use organized folder structure
+5. **No frontend changes required** - existing code continues to work
+
+The enhancement enables better organization of `.forloop/` planning artifacts while maintaining complete compatibility with existing frontend clients and workflows.