From f04badf9f4f0ac09f1ce4a1ed9adaa1251f124db Mon Sep 17 00:00:00 2001 From: Nexus Dev Date: Thu, 2 Apr 2026 00:14:08 +0000 Subject: [PATCH] =?UTF-8?q?docs(25-07):=20complete=20agent-generated=20fil?= =?UTF-8?q?e=20support=20and=20placeholder=20tracking=20plan=20=E2=80=94?= =?UTF-8?q?=20SUMMARY,=20STATE,=20ROADMAP=20updated?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .planning/ROADMAP.md | 8 +- .planning/STATE.md | 18 +-- .../phases/25-file-system/25-07-SUMMARY.md | 109 ++++++++++++++++++ 3 files changed, 124 insertions(+), 11 deletions(-) create mode 100644 .planning/phases/25-file-system/25-07-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index e0ebf290..ebc58bb3 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -14,7 +14,7 @@ - [x] **Phase 22: Agent Streaming** — Real-time streaming via SSE/WebSocket, agent selector, agent identity on messages, stop/edit/regenerate, slash commands and @mentions (completed 2026-04-01) - [x] **Phase 23: Brainstormer Flow** — Brainstormer agent persona, structured questioning flow, spec generation, PM handoff, task creation from chat, agent status updates in chat (completed 2026-04-01) - [x] **Phase 24: Search, History & Branching** — Full-text search across all conversations, export, conversation branching, message bookmarks (completed 2026-04-01) -- [ ] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking (gap closure in progress) +- [x] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking (gap closure in progress) (completed 2026-04-02) - [ ] **Phase 26: PWA & Performance** — Service worker, Web App Manifest, responsive mobile layout, push notifications, install prompt, performance targets --- @@ -116,7 +116,7 @@ Plans: 5. When an agent generates a placeholder asset, `PLACEHOLDERS.md` is updated in the project directory; when the placeholder is replaced, the DB records the replacement chain and the manifest reflects the change 6. A file uploaded in a conversation linked to a project lives in `files/projects//`; a file from an unlinked conversation lives in `files/chat//`; the user can promote a chat file to project scope 7. Voice input is available when local AI is enabled: user can hold the record button, speak, see a transcription preview, and confirm to send -**Plans:** 8/9 plans executed +**Plans:** 9/9 plans complete Plans: - [x] 25-00-PLAN.md — DB schema (chat_files + chat_file_references), shared types/validators, test stubs @@ -126,7 +126,7 @@ Plans: - [x] 25-04-PLAN.md — Gap: Code syntax-highlighted preview (FILE-06) + admin claims (FILE-07, FILE-13) - [x] 25-05-PLAN.md — Gap: File scope promotion API + UI (FILE-12) - [x] 25-06-PLAN.md — Gap: Git integration for file operations + version history (FILE-09, FILE-10) -- [ ] 25-07-PLAN.md — Gap: Agent-generated files + placeholder tracking (FILE-08, FILE-11) +- [x] 25-07-PLAN.md — Gap: Agent-generated files + placeholder tracking (FILE-08, FILE-11) - [x] 25-08-PLAN.md — Gap: Voice input via Whisper (INPUT-04) + admin claims (INPUT-02, INPUT-03) **UI hint**: yes @@ -227,5 +227,5 @@ All 65 v1 requirements are mapped to exactly one phase. No orphans. | 22. Agent Streaming | v1.3 | 6/6 | Complete | 2026-04-01 | | 23. Brainstormer Flow | v1.3 | 4/4 | Complete | 2026-04-01 | | 24. Search, History & Branching | v1.3 | 4/4 | Complete | 2026-04-01 | -| 25. File System | v1.3 | 8/9 | In Progress| | +| 25. File System | v1.3 | 9/9 | Complete | 2026-04-02 | | 26. PWA & Performance | v1.3 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 4961bfdf..8eba5ab1 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.3 milestone_name: milestone status: executing -stopped_at: Completed 25-file-system-25-06-PLAN.md -last_updated: "2026-04-02T00:06:07.957Z" +stopped_at: Completed 25-file-system-25-07-PLAN.md +last_updated: "2026-04-02T00:13:52.105Z" last_activity: 2026-04-02 progress: total_phases: 6 - completed_phases: 4 + completed_phases: 5 total_plans: 30 - completed_plans: 29 + completed_plans: 30 percent: 100 --- @@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-03-30) ## Current Position Phase: 25 (file-system) — EXECUTING -Plan: 4 of 9 +Plan: 5 of 9 Status: Ready to execute Last activity: 2026-04-02 @@ -85,6 +85,7 @@ Progress: [██████████] 100% | Phase 25-file-system P08 | 8 | 2 tasks | 5 files | | Phase 25-file-system P04 | 5min | 2 tasks | 5 files | | Phase 25-file-system P06 | 5 | 2 tasks | 5 files | +| Phase 25-file-system P07 | 10 | 2 tasks | 6 files | ## Accumulated Context @@ -157,6 +158,9 @@ Recent decisions affecting current work: - [Phase 25-file-system]: Used execFile (not exec) for git commands in gitFileService — array-based args prevent shell injection - [Phase 25-file-system]: Git commit is fire-and-forget after upload — response not blocked by git operation - [Phase 25-file-system]: History route placed before /content route to avoid Express path ambiguity on /files/:fileId/* +- [Phase 25-file-system]: placeholderService reads/writes PLACEHOLDERS.md using regex row parser to avoid markdown deps +- [Phase 25-file-system]: addEntry is fire-and-forget — response not blocked by placeholder manifest I/O +- [Phase 25-file-system]: resolveDefaultStorageDir() used for projectDir in placeholder service — consistent with git-file-service pattern ### Pending Todos @@ -169,6 +173,6 @@ None yet. ## Session Continuity -Last session: 2026-04-02T00:06:07.954Z -Stopped at: Completed 25-file-system-25-06-PLAN.md +Last session: 2026-04-02T00:13:52.102Z +Stopped at: Completed 25-file-system-25-07-PLAN.md Resume file: None diff --git a/.planning/phases/25-file-system/25-07-SUMMARY.md b/.planning/phases/25-file-system/25-07-SUMMARY.md new file mode 100644 index 00000000..4436a05b --- /dev/null +++ b/.planning/phases/25-file-system/25-07-SUMMARY.md @@ -0,0 +1,109 @@ +--- +phase: 25-file-system +plan: 07 +subsystem: api +tags: [placeholder, agent-generated, manifest, markdown, chat-files] + +requires: + - phase: 25-01 + provides: chatFileService with create/getById/createReference methods + - phase: 25-06 + provides: git-file-service with storageDir pattern (on separate worktree; storageDir import added here) + +provides: + - placeholderService with addEntry/replaceEntry/listEntries managing PLACEHOLDERS.md + - chatFileService.markAsPlaceholder method + - POST /files/:fileId/replace endpoint for placeholder replacement + - Agent-generated file tracking in PLACEHOLDERS.md manifest + +affects: [25-06, future-agent-file-generation] + +tech-stack: + added: [] + patterns: + - placeholderService reads/writes PLACEHOLDERS.md markdown tables + - fire-and-forget phSvc.addEntry() on upload (non-blocking) + - replace endpoint updates manifest + creates reference chain atomically + +key-files: + created: + - server/src/services/placeholder-service.ts + modified: + - server/src/services/chat-files.ts + - server/src/routes/chat-files.ts + - packages/shared/src/types/chat.ts + - packages/shared/src/index.ts + - .planning/REQUIREMENTS.md + +key-decisions: + - "placeholderService reads/writes PLACEHOLDERS.md using regex row parser to avoid markdown deps" + - "addEntry is fire-and-forget (.catch(() => {})) — response not blocked by file I/O" + - "replaceEntry is awaited in /replace endpoint — manifest must be consistent before response" + - "resolveDefaultStorageDir() used for projectDir path — consistent with git-file-service pattern" + +patterns-established: + - "Placeholder manifest: Active Placeholders and Replaced markdown tables in PLACEHOLDERS.md per project dir" + - "Replace endpoint: phSvc.replaceEntry + fileSvc.createReference for atomically updating both manifest and DB" + +requirements-completed: [FILE-08, FILE-11] + +duration: 10min +completed: 2026-04-02 +--- + +# Phase 25 Plan 07: Agent-Generated File Support and Placeholder Tracking Summary + +**PLACEHOLDERS.md manifest service with addEntry/replaceEntry and POST /files/:fileId/replace endpoint wiring agent-generated uploads to per-project markdown manifests** + +## Performance + +- **Duration:** ~10 min +- **Started:** 2026-04-02T00:09:00Z +- **Completed:** 2026-04-02T00:12:49Z +- **Tasks:** 2 +- **Files modified:** 5 + +## Accomplishments +- Created `placeholder-service.ts` with full PLACEHOLDERS.md markdown table management (addEntry, replaceEntry, listEntries) +- Added `markAsPlaceholder` method to `chatFileService` for DB-level placeholder categorization +- Wired agent_generated + project-scoped uploads to automatically update PLACEHOLDERS.md +- Added `POST /files/:fileId/replace` endpoint that updates manifest and creates DB reference chain +- Marked FILE-08 and FILE-11 Complete in REQUIREMENTS.md + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Create placeholderService and add markAsPlaceholder method** - `0a80659c` (feat) +2. **Task 2: Add placeholder and agent-generated file routes** - `2a4037ca` (feat) + +## Files Created/Modified +- `server/src/services/placeholder-service.ts` - PLACEHOLDERS.md manifest management service (161 lines) +- `server/src/services/chat-files.ts` - Added markAsPlaceholder method +- `server/src/routes/chat-files.ts` - Added phSvc import, agent_generated tracking, /replace endpoint +- `packages/shared/src/types/chat.ts` - Added ChatPlaceholderEntry interface +- `packages/shared/src/index.ts` - Exported ChatPlaceholderEntry +- `.planning/REQUIREMENTS.md` - Marked FILE-08 and FILE-11 Complete + +## Decisions Made +- Used regex row parser (`/^\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/`) to parse markdown tables — no external markdown deps needed +- `addEntry` is fire-and-forget (non-blocking) to avoid blocking upload response +- `replaceEntry` is awaited in the replace endpoint for manifest consistency before response +- Used `resolveDefaultStorageDir()` for project dir base path, consistent with 25-06 storageDir pattern +- `git-file-service.ts` not present on this branch (in 25-06 worktree); storageDir import added here for placeholder path only + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +- `git-file-service.ts` not present on current branch (it's in the 25-06 worktree). Per the important_context note, proceeded with placeholder-service implementation and imported `resolveDefaultStorageDir` directly for the project path computation. No blocking impact. + +## Next Phase Readiness +- PLACEHOLDERS.md manifest management complete; any agent that uploads with source=agent_generated and projectId will auto-track +- Replace endpoint ready for agent workflows that upgrade placeholder assets to final outputs +- FILE-08 and FILE-11 marked complete + +--- +*Phase: 25-file-system* +*Completed: 2026-04-02*