# Local File Import — Execution Board

**Created:** 2026-03-28  
**Owner:** Cleo (orchestrator)  
**Goal:** Implement functionality to import recipes from local .txt and .html files exported from CopyMeThat  
**Status:** 🚧 In Progress

---

## Context

Paul has exported recipes from CopyMeThat in both .txt and .html formats. The Recipe Manager currently lacks functionality to import local files. This execution board tracks the implementation of this feature from file parsing through UI integration.

**Critical constraint:** Sub-agent spawning is currently blocked, so all work will be done in the main thread by Cleo.

---

## Task Breakdown

### Phase 1: Analysis & Design ✅
**Status:** Complete  
**Tasks:**
- [x] T1.1: Analyze CopyMeThat export file formats (.txt and .html)
- [x] T1.2: Design import data pipeline (parse → validate → insert)
- [x] T1.3: Define backend API endpoint contract
- [x] T1.4: Define frontend UI flow (file selection → preview → confirm)

**Deliverables:**
- ✅ File format specification document (`.harness/local-file-import-phase1-analysis.md`)
- ✅ Import service architecture design
- ✅ API endpoint spec
- ✅ UI wireframe/flow diagram

---

### Phase 2: Backend Implementation 🚧
**Status:** In Progress (90% complete)  
**Tasks:**
- [x] T2.0: Extend database schema with `made`, `rating`, `notes` fields
- [x] T2.1: Create file parser for .txt format (`CopyMeThatTxtParser.ts`)
- [x] T2.2: Create file parser for .html format (`CopyMeThatHtmlParser.ts`)
- [x] T2.3: Implement import service with duplicate detection (`CopyMeThatImportService.ts`)
- [x] T2.4: Create POST `/api/import/local` endpoint with multer file upload
- [x] T2.5: Register route in Express app
- [x] T2.6: Install multer dependency
- [ ] T2.7: Add unit tests for parsers
- [ ] T2.8: Add integration tests for import endpoint

**Deliverables:**
- ✅ `src/backend/services/CopyMeThatHtmlParser.ts`
- ✅ `src/backend/services/CopyMeThatTxtParser.ts`
- ✅ `src/backend/services/CopyMeThatImportService.ts`
- ✅ `src/backend/routes/importLocal.ts`
- ✅ Schema migration (`migrations/2026-03-28-add-user-metadata-fields.md`)
- ⏳ Test coverage (pending)

---

### Phase 3: Frontend Implementation
**Status:** Pending  
**Tasks:**
- [ ] T3.1: Create file upload component with drag-and-drop
- [ ] T3.2: Build import preview screen (show parsed recipes before commit)
- [ ] T3.3: Add progress indicator for batch imports
- [ ] T3.4: Implement error handling & user feedback
- [ ] T3.5: Add import page to navigation

**Deliverables:**
- `src/frontend/components/ImportRecipes.tsx`
- `src/frontend/components/ImportPreview.tsx`
- `src/frontend/pages/ImportPage.tsx`
- Styling consistent with existing UI

---

### Phase 4: Testing & Polish
**Status:** Pending  
**Tasks:**
- [ ] T4.1: End-to-end test: import single .txt file
- [ ] T4.2: End-to-end test: import single .html file
- [ ] T4.3: End-to-end test: batch import multiple files
- [ ] T4.4: Manual testing with Paul's actual CopyMeThat exports
- [ ] T4.5: Performance testing (100+ recipes)
- [ ] T4.6: Update user documentation

**Deliverables:**
- E2E test suite
- Performance benchmarks
- Updated `docs/user-guide.md` with import instructions

---

### Phase 5: Deployment
**Status:** Pending  
**Tasks:**
- [ ] T5.1: Build and test Docker image
- [ ] T5.2: Deploy to paje.ca staging
- [ ] T5.3: User acceptance testing (Anne & Elizabeth)
- [ ] T5.4: Production deployment
- [ ] T5.5: Data migration (import Paul's CopyMeThat exports)

**Deliverables:**
- Deployed feature on recipes.paje.ca
- Migrated recipe data
- Release notes

---

## Dependencies

- CopyMeThat export sample files (need from Paul)
- Existing Recipe schema/validation (already implemented)
- Current backend API structure
- Frontend routing and navigation patterns

---

## Technical Decisions

### File Format Handling
- **Decision:** Support both .txt and .html, with .html as primary (more structured data)
- **Rationale:** .txt is human-readable backup, .html likely has better metadata
- **Risk:** Unknown format specifics until we see sample files

### Duplicate Detection
- **Decision:** Check for exact title + ingredients match
- **Rationale:** Simple, fast, low false-positive rate
- **Alternative:** Could add fuzzy matching later (v1.1)

### Batch Import Strategy
- **Decision:** Parse all files first, show preview, then bulk insert
- **Rationale:** Gives user control, prevents partial imports on error
- **Trade-off:** Higher memory usage for large batches (acceptable for <1000 recipes)

### Error Recovery
- **Decision:** Log failures, continue processing remaining files
- **Rationale:** One bad file shouldn't block entire import
- **UX:** Show summary with success/failure counts

---

## Risks & Mitigation

| Risk | Impact | Mitigation |
|------|--------|------------|
| Unknown file format structure | High | Request sample files from Paul immediately |
| Large file performance | Medium | Implement streaming parser if needed |
| Encoding issues (UTF-8, special chars) | Medium | Use robust parser library, test with international recipes |
| Duplicate recipe handling | Low | Clear UI messaging, offer merge/skip options |

---

## Acceptance Criteria

✅ **Must Have:**
1. User can upload .txt or .html files via UI
2. System correctly parses CopyMeThat export formats
3. User sees preview of recipes before import
4. Duplicate detection prevents accidental re-imports
5. Batch import works for 100+ files
6. Clear error messages for invalid files
7. Documentation updated with import instructions

🎯 **Nice to Have:**
- Drag-and-drop file upload
- Progress bar for large batches
- Import history log
- Undo/rollback option

---

## Progress Log

**2026-03-28 23:46 EDT — Kickoff**
- Execution board created
- Awaiting CopyMeThat export sample files from Paul
- Next step: Analyze file formats and begin Phase 1

---

## Notes

- Paul has files ready in Downloads folder (.txt and .html)
- Sub-agent spawning currently broken, all work in main thread
- Target completion: 24-48 hours (depending on file format complexity)
- This feature unblocks Anne & Elizabeth from migrating to Recipe Manager

---

_Last updated: 2026-03-28 23:50 EDT by Cleo_
