mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

test(25): persist human verification items as UAT

Browse source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Nexus Dev 2026-04-02 00:28:00 +00:00
parent dae0e3a3be
commit d134272779
2 changed files with 311 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
.planning/phases/25-file-system/25-HUMAN-UAT.md Normal file
View file

@ -0,0 +1,56 @@
---
status: partial
phase: 25-file-system
source: [25-VERIFICATION.md]
started: 2026-04-01T00:25:00Z
updated: 2026-04-01T00:25:00Z
---
## Current Test
[awaiting human testing]
## Tests
### 1. Drag a file onto the chat input area
expected: Drop zone overlay appears with dashed border and 'Drop files here' text; on release, file uploads with progress chip visible
result: [pending]
### 2. Paste an image from clipboard into the chat textarea
expected: Image upload begins immediately, progress chip appears above textarea
result: [pending]
### 3. Click the Paperclip button in ChatInput, select a file
expected: Native file picker opens; selecting a file starts the upload and shows a pending chip
result: [pending]
### 4. View a message with an attached code file (.ts, .py, etc.)
expected: ChatCodeFilePreview renders with syntax highlighting, copy button, language label, and a download card below
result: [pending]
### 5. Click the microphone button, speak, then click the stop button
expected: Loader2 spinner while transcribing; transcription text inserted into textarea
result: [pending]
### 6. In a project-linked conversation, click the FolderUp button on a ChatFileCard
expected: File is promoted to project scope; FolderUp button disappears
result: [pending]
### 7. Upload any file and inspect the storage directory with 'git log'
expected: A new commit with message 'Upload: <filename>' appears in the git log for the storage directory
result: [pending]
### 8. Call GET /api/files/:fileId/history for an uploaded file
expected: JSON response with 'items' array containing objects with hash, date, message, author fields
result: [pending]
## Summary
total: 8
passed: 0
issues: 0
pending: 8
skipped: 0
blocked: 0
## Gaps

255
.planning/phases/25-file-system/25-VERIFICATION.md Normal file
View file

@ -0,0 +1,255 @@
---
phase: 25-file-system
verified: 2026-04-01T00:00:00Z
status: human_needed
score: 15/15 must-haves verified
re_verification: true
previous_status: gaps_found
previous_score: 13/15
gaps_closed:
- "Every file upload creates a git commit in the storage directory (FILE-09) — git-file-service.ts now exists and commitFile is called in the upload handler"
- "User can view the git log (version history) for any file (FILE-10) — GET /files/:fileId/history route now present in chat-files.ts"
gaps_remaining: []
regressions: []
human_verification:
- test: "Drag a file onto the chat input area"
expected: "Drop zone overlay appears with dashed border and 'Drop files here' text; on release, file uploads with progress chip visible"
why_human: "Drag-and-drop visual feedback and upload progress require a running browser"
- test: "Paste an image from clipboard into the chat textarea"
expected: "Image upload begins immediately, progress chip appears above textarea"
why_human: "Clipboard paste interaction requires a running browser"
- test: "Click the Paperclip button in ChatInput, select a file"
expected: "Native file picker opens; selecting a file starts the upload and shows a pending chip"
why_human: "Native file picker requires a running browser"
- test: "View a message with an attached code file (.ts, .py, etc.)"
expected: "ChatCodeFilePreview renders with syntax highlighting, copy button, language label, and a download card below"
why_human: "highlight.js rendering and layout require a running browser"
- test: "Click the microphone button, speak, then click the stop button"
expected: "Loader2 spinner while transcribing; transcription text inserted into textarea"
why_human: "MediaRecorder API, microphone permission, and UI state transitions require a running browser"
- test: "In a project-linked conversation, click the FolderUp button on a ChatFileCard"
expected: "File is promoted to project scope; FolderUp button disappears"
why_human: "Requires running app with real project context and DB writes"
- test: "Upload any file in a conversation and inspect the storage directory with 'git log'"
expected: "A new commit with message 'Upload: <filename>' appears in the git log for the storage directory"
why_human: "Requires a running server and real file system git operations to verify end-to-end"
- test: "Call GET /api/files/:fileId/history for an uploaded file"
expected: "JSON response with 'items' array containing objects with hash, date, message, author fields"
why_human: "Requires a running server with a file that has been committed to git storage"
---
# Phase 25: File System Verification Report (Final Re-verification)
**Phase Goal:** Users and agents can upload, generate, preview, and download files in chat, with all files tracked in libSQL, version-controlled by git, and accessible across devices
**Verified:** 2026-04-01T00:00:00Z
**Status:** human_needed (all automated checks pass)
**Re-verification:** Yes — after merging worktree code for FILE-09/FILE-10
## Re-verification Summary
This is the third verification pass for Phase 25. The previous verification (score 13/15) identified two gaps:
1. `server/src/services/git-file-service.ts` did not exist on the deliverable branch (was in a separate worktree).
2. `GET /files/:fileId/history` route was absent in `server/src/routes/chat-files.ts`.
Both gaps have been resolved. The merged code has been verified to be substantive and correctly wired.
**No regressions detected** — all 13 previously-verified truths remain intact.
---
## Goal Achievement
### Observable Truths
| # | Truth | Status | Evidence |
|----|------------------------------------------------------------------------------------|------------|-----------------------------------------------------------------------------------------------|
| 1 | Users can upload files via drag-and-drop, button, or clipboard paste | VERIFIED | ChatFileDropZone, useChatFileUpload hook, ChatInput integration all present |
| 2 | Uploaded files are persisted to disk and tracked in libSQL | VERIFIED | StorageService.putFile + chatFileService.create in POST /conversations/:id/files |
| 3 | File metadata tracked with dual scope (project + conversation) | VERIFIED | chat_files schema has projectId FK + conversationId; deriveCategory in service |
| 4 | File references table enables multi-conversation reuse without duplication | VERIFIED | chat_file_references schema + createReference method wired in routes |
| 5 | Images render inline in chat messages | VERIFIED | ChatFilePreview branches on category === "image" and renders `<img>` inline |
| 6 | Code files show syntax-highlighted preview in chat | VERIFIED | ChatCodeFilePreview (176 lines): fetch content, hljs.highlight, paperclip-markdown class |
| 7 | One-click file download from chat | VERIFIED | ChatFileCard download anchor present; REQUIREMENTS.md marked Complete |
| 8 | Agent-generated files tracked in PLACEHOLDERS.md manifest | VERIFIED | placeholderService (161 lines) + phSvc.addEntry called for agent_generated uploads |
| 9 | Every file upload creates a git commit in the storage directory | VERIFIED | gitSvc.commitFile called at line 106 of chat-files.ts; git-file-service.ts (101 lines) substantive |
| 10 | User can view version history (git log) for any file | VERIFIED | GET /files/:fileId/history route at lines 136-151 of chat-files.ts; gitSvc.getLog wired |
| 11 | File scope promotion: chat-scoped file promotable to project scope | VERIFIED | PATCH /files/:fileId/promote + ChatFileCard FolderUp button + chatApi.promoteFile |
| 12 | Cross-device file access via HTTP API | VERIFIED | GET /files/:fileId/content streams over HTTP; REQUIREMENTS.md marked Complete |
| 13 | User can record voice audio and receive transcription in chat input | VERIFIED | VoiceRecordButton (109 lines) + POST /transcribe + ChatInput enableVoiceInput wired |
| 14 | INPUT-02/INPUT-03 file drag-and-drop and clipboard paste | VERIFIED | ChatFileDropZone + handlePaste in ChatInput wired |
| 15 | TypeScript compiles without errors in phase-25 files | VERIFIED | tsc --noEmit: zero errors in git-file-service.ts, chat-files.ts, or any other phase-25 file (pre-existing plugin-sdk errors are unrelated) |
**Score:** 15/15 truths verified
---
### Required Artifacts
| Artifact | Status | Details |
|------------------------------------------------------|-------------|--------------------------------------------------------------------------------------------|
| `packages/db/src/schema/chat_files.ts` | VERIFIED | Dual-scope schema with projectId FK, conversationId, source, category columns |
| `packages/db/src/schema/chat_file_references.ts` | VERIFIED | Cross-reference table schema present |
| `packages/shared/src/types/chat.ts` | VERIFIED | ChatFile, ChatFileReference, ChatPlaceholderEntry, ChatFileHistoryEntry all present |
| `server/src/services/chat-files.ts` | VERIFIED | create, getById, listByConversation, attachToMessage, promoteToProject, markAsPlaceholder |
| `server/src/routes/chat-files.ts` | VERIFIED | Upload, download, references, promote, replace, transcribe, and history routes all present |
| `server/src/services/git-file-service.ts` | VERIFIED | 101 lines; ensureRepo, commitFile, getLog; uses execFile("git", ...) with real git calls |
| `server/src/services/placeholder-service.ts` | VERIFIED | 161 lines; addEntry, replaceEntry, listEntries; PLACEHOLDERS.md markdown table management |
| `ui/src/components/ChatFileDropZone.tsx` | VERIFIED | Drop zone overlay component present |
| `ui/src/components/ChatFilePreview.tsx` | VERIFIED | Branches: image inline, code to ChatCodeFilePreview, fallback ChatFileCard |
| `ui/src/components/ChatCodeFilePreview.tsx` | VERIFIED | 176 lines; hljs.highlight, fetch(contentPath), extToLang, max-h-[400px], ChatFileCard |
| `ui/src/components/ChatFileCard.tsx` | VERIFIED | 94 lines; download anchor, FolderUp promote button, chatApi.promoteFile call |
| `ui/src/components/VoiceRecordButton.tsx` | VERIFIED | 109 lines; MediaRecorder, fetch /api/transcribe, recording/transcribing/idle states |
| `ui/src/api/chat.ts` | VERIFIED | uploadFile, attachFilesToMessage, promoteFile methods present |
---
### Key Link Verification
| From | To | Via | Status | Details |
|-------------------------------|-------------------------------------------|-----------------------------------|-----------|-----------------------------------------------------------------------|
| ChatFilePreview.tsx | ChatCodeFilePreview.tsx | import + code category branch | WIRED | `import { ChatCodeFilePreview }` + `file.category === "code"` branch |
| ChatCodeFilePreview.tsx | /api/files/:fileId/content | fetch(contentPath) | WIRED | `fetch(contentPath, { credentials: "include" })` at line 87 |
| ChatFileCard.tsx | chatApi.promoteFile | promoteFile call in promote button | WIRED | `chatApi.promoteFile(file.id, projectId)` at line 65 |
| server/routes/chat-files.ts | placeholder-service.ts | phSvc.addEntry | WIRED | `phSvc.addEntry(projectDir, {...})` at lines 111-115 |
| server/routes/chat-files.ts | chat-files.ts service | fileSvc.promoteToProject | WIRED | `fileSvc.promoteToProject(fileId, projectId)` at line 214 |
| server/routes/chat-files.ts | git-file-service.ts | gitSvc.commitFile | WIRED | `gitSvc.commitFile(storageDir, stored.objectKey, ...)` at line 106 |
| server/routes/chat-files.ts | git-file-service.ts | gitSvc.getLog in /history route | WIRED | `gitSvc.getLog(storageDir, chatFile.objectKey, limit)` at line 149 |
| ChatInput.tsx | VoiceRecordButton.tsx | import + enableVoiceInput prop | WIRED | `import { VoiceRecordButton }` + `{enableVoiceInput && <VoiceRecordButton ...>}` |
| VoiceRecordButton.tsx | /api/transcribe | fetch POST with audio FormData | WIRED | `fetch("/api/transcribe", { method: "POST", body: formData })` |
| ChatPanel.tsx | ChatInput enableVoiceInput | prop pass-through | WIRED | `enableVoiceInput={true}` at line 391 |
---
### Data-Flow Trace (Level 4)
| Artifact | Data Variable | Source | Produces Real Data | Status |
|------------------------------|------------------|-----------------------------------|--------------------|-----------|
| ChatCodeFilePreview.tsx | content (string) | fetch(contentPath) → .text() | Yes | FLOWING |
| ChatFileCard.tsx | file.projectId | prop from parent component | Yes | FLOWING |
| VoiceRecordButton.tsx | transcription | POST /transcribe → res.json() | Yes (or 503) | FLOWING |
| GET /files/:fileId/history | entries array | gitSvc.getLog → git log stdout | Yes | FLOWING |
---
### Behavioral Spot-Checks
| Behavior | Command / Check | Result | Status |
|----------------------------------------------------|--------------------------------------------------------------------------|-----------------------------------------------------|--------|
| git-file-service.ts exists on current branch | `ls server/src/services/git-file-service.ts` | File present, 101 lines | PASS |
| git-file-service.ts uses real git calls | grep "execFile" git-file-service.ts | `execFile("git", args, ...)` at line 23 | PASS |
| gitSvc import in chat-files routes | grep "git-file-service" server/src/routes/chat-files.ts | `import { gitFileService }` at line 12 | PASS |
| gitSvc.commitFile called on upload | grep "commitFile" server/src/routes/chat-files.ts | `gitSvc.commitFile(...)` at line 106 | PASS |
| GET /files/:fileId/history route exists | grep "/history" server/src/routes/chat-files.ts | Route at lines 136-151 | PASS |
| gitSvc.getLog wired in /history route | grep "getLog" server/src/routes/chat-files.ts | `gitSvc.getLog(storageDir, ...)` at line 149 | PASS |
| ChatFileHistoryEntry exported from shared | grep "ChatFileHistoryEntry" packages/shared/src/index.ts | Exported at line 595 | PASS |
| ChatFileHistoryEntry interface fields correct | grep -A5 "ChatFileHistoryEntry" shared/src/types/chat.ts | hash, date, message, author fields — matches gitSvc | PASS |
| No TS errors in phase-25 files | tsc --noEmit (server) — filter phase-25 files | Zero errors; only pre-existing plugin-sdk errors | PASS |
| placeholderService still 161 lines | wc -l placeholder-service.ts | 161 | PASS |
| VoiceRecordButton still 109 lines | wc -l VoiceRecordButton.tsx | 109 | PASS |
| ChatCodeFilePreview still 176 lines | wc -l ChatCodeFilePreview.tsx | 176 | PASS |
| promote route still present | grep -c "promote" server/src/routes/chat-files.ts | 3 matches | PASS |
---
### Requirements Coverage
| Requirement | Source Plans | Description (short) | Status | Evidence |
|-------------|-------------------|--------------------------------------------------------|-----------|-----------------------------------------------------------------------|
| FILE-01 | 25-00 | Local file storage directory structure | SATISFIED | Schema + StorageService directory layout |
| FILE-02 | 25-00 | libSQL files table with full metadata | SATISFIED | chat_files schema with all required columns |
| FILE-03 | 25-00 | libSQL file_references table | SATISFIED | chat_file_references schema + createReference service method |
| FILE-04 | 25-00, 25-01 | Dual scoping (project + conversation) | SATISFIED | projectId nullable FK + conversationId on chatFiles |
| FILE-05 | 25-02 | File upload via drag-and-drop or button | SATISFIED | ChatFileDropZone + useChatFileUpload + multer upload route |
| FILE-06 | 25-03, 25-04 | Inline preview: images inline, code syntax-highlighted | SATISFIED | ChatFilePreview + ChatCodeFilePreview with hljs |
| FILE-07 | 25-04 | One-click download from chat | SATISFIED | ChatFileCard download anchor; REQUIREMENTS.md marked Complete |
| FILE-08 | 25-07 | Agent-generated files tracked and linked | SATISFIED | placeholderService + agent_generated branch in upload route |
| FILE-09 | 25-06 | Git integration: every upload creates a commit | SATISFIED | git-file-service.ts (101 lines) + gitSvc.commitFile at line 106 |
| FILE-10 | 25-06 | Version history: user can view git log per file | SATISFIED | GET /files/:fileId/history at lines 136-151; gitSvc.getLog wired |
| FILE-11 | 25-07 | PLACEHOLDERS.md manifest auto-maintained | SATISFIED | placeholder-service.ts (161 lines) with addEntry/replaceEntry |
| FILE-12 | 25-05 | File scope promotion from chat to project | SATISFIED | PATCH /files/:fileId/promote + ChatFileCard FolderUp button |
| FILE-13 | 25-04 | Cross-device access via HTTP API | SATISFIED | GET /files/:fileId/content serves stream; REQUIREMENTS.md Complete |
| INPUT-02 | 25-02, 25-08 | File/image upload via drag-and-drop or button | SATISFIED | ChatFileDropZone + upload hook + ChatInput integration |
| INPUT-03 | 25-02, 25-08 | Paste image from clipboard | SATISFIED | handlePaste in ChatInput wired to upload hook |
| INPUT-04 | 25-08 | Voice input via Whisper with transcription preview | SATISFIED | VoiceRecordButton + POST /transcribe + handleTranscription callback |
All 16 requirement IDs satisfied. No orphaned requirements.
---
### Anti-Patterns Found
None blocking. The git commit call at line 106 uses `.catch(() => {})` (fire-and-forget), which is intentional — a git commit failure should not fail the upload. This is acceptable.
---
### Human Verification Required
#### 1. Drag-and-drop file upload
**Test:** Drag any file onto the chat input area
**Expected:** Drop zone overlay with dashed border and "Drop files here" text; on release, file uploads with a progress chip
**Why human:** Drag-and-drop visual feedback requires a running browser
#### 2. Clipboard paste upload
**Test:** Copy a screenshot image, focus the chat textarea, paste (Ctrl+V or Cmd+V)
**Expected:** Image upload begins immediately, progress chip appears above textarea
**Why human:** Clipboard paste requires a running browser
#### 3. File picker upload
**Test:** Click the Paperclip button in ChatInput, select any file from the native picker
**Expected:** Native file picker opens; selecting a file starts the upload and shows a pending chip above the textarea
**Why human:** Native file picker requires a running browser
#### 4. Syntax-highlighted code preview
**Test:** Attach a .ts or .py file to a chat message and view the sent message
**Expected:** ChatCodeFilePreview renders with syntax highlighting, copy button, language label, and download card below
**Why human:** highlight.js rendering requires a running browser
#### 5. Voice input transcription
**Test:** Click the microphone icon, speak a sentence, click the stop (square) button
**Expected:** Loader2 spinner shows while transcribing; transcription text inserted into textarea
**Why human:** MediaRecorder API and microphone permission require a running browser with audio hardware
#### 6. File scope promote button
**Test:** In a project-linked conversation, view a ChatFileCard. Click the FolderUp button.
**Expected:** File is promoted to project scope; FolderUp button disappears from the card
**Why human:** Requires running app with real project context and DB state
#### 7. Git commit created on file upload
**Test:** Upload a file via the chat interface. On the server, inspect the storage directory: `git -C <storage_dir> log --oneline` should show a new commit "Upload: <filename>"
**Expected:** A commit with the upload message appears in the git log
**Why human:** Requires running server with access to the file system storage directory
#### 8. File history API returns git log entries
**Test:** After uploading a file, call `GET /api/files/:fileId/history`
**Expected:** `{ "items": [{ "hash": "...", "date": "...", "message": "Upload: ...", "author": "Nexus File System" }] }`
**Why human:** Requires running server and a file that has been committed to git storage
---
## Summary
**All 15 observable truths are now VERIFIED.** All 16 requirements are SATISFIED. No blocking anti-patterns.
The two gaps from the previous verification (FILE-09 git integration, FILE-10 history endpoint) have been resolved by merging the worktree code:
- `server/src/services/git-file-service.ts` — 101 lines; substantive implementation using `execFile("git", ...)` with `ensureRepo`, `commitFile`, and `getLog` methods
- `server/src/routes/chat-files.ts` — now imports `gitFileService`, instantiates `gitSvc`, calls `gitSvc.commitFile` non-blocking on upload (line 106), and serves `GET /files/:fileId/history` via `gitSvc.getLog` (lines 136-151)
- `packages/shared/src/types/chat.ts` — `ChatFileHistoryEntry` interface (hash, date, message, author) exported from the shared package
No regressions detected in any previously-verified artifact.
The phase goal is **achieved at the code level**. Eight items require human browser/server verification for final confirmation of end-to-end behavior.
---
_Verified: 2026-04-01T00:00:00Z_
_Verifier: Claude (gsd-verifier) — final re-verification after worktree merge_