docs(24-01): complete search-history-branching plan 01 — service methods and routes

- SUMMARY.md: 6 service methods + 6 route handlers documented - STATE.md: advanced to plan 3/4, recorded metrics and decisions - ROADMAP.md: updated phase 24 progress (2/4 summaries)
2026-04-01 22:33:21 +00:00 · 2026-04-01 22:33:21 +00:00 · 85bd30b6ee
commit 85bd30b6ee
parent ac6d75ab0d
3 changed files with 130 additions and 9 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -94,11 +94,11 @@ Plans:
  2. User can bookmark any message and later filter or navigate to bookmarked messages
  3. Editing a message that already has a response creates a new branch; both the original and the new branch are preserved and the user can switch between them
  4. User can export any conversation as a Markdown file or as a JSON file containing all messages and metadata
-**Plans:** 1/4 plans executed
+**Plans:** 2/4 plans executed

 Plans:
 - [x] 24-00-PLAN.md — DB migrations (branch columns, tsvector+GIN, bookmarks table), shared types, Wave 0 test stubs
- [ ] 24-01-PLAN.md — Server: search, bookmark, branch, export service methods and Express routes
+- [x] 24-01-PLAN.md — Server: search, bookmark, branch, export service methods and Express routes
 - [ ] 24-02-PLAN.md — UI: ChatSearchDialog, ChatMessageBookmark, ChatBookmarkList, ChatBranchSelector, API client, hooks
 - [ ] 24-03-PLAN.md — Wiring: ChatPanel integration, CommandPalette search item, scroll-to-message, bookmark toggle, branch-on-edit

@ -214,6 +214,6 @@ All 65 v1 requirements are mapped to exactly one phase. No orphans.
 | 21. Chat Foundation | v1.3 | 7/7 | Complete    | 2026-04-01 |
 | 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 | 1/4 | In Progress|  |
+| 24. Search, History & Branching | v1.3 | 2/4 | In Progress|  |
 | 25. File System | v1.3 | 0/? | Not started | - |
 | 26. PWA & Performance | v1.3 | 0/? | Not started | - |
--- 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 24-search-history-branching-24-00-PLAN.md
-last_updated: "2026-04-01T22:28:30.760Z"
+stopped_at: Completed 24-search-history-branching-24-01-PLAN.md
+last_updated: "2026-04-01T22:33:10.664Z"
 last_activity: 2026-04-01
 progress:
  total_phases: 6
  completed_phases: 3
  total_plans: 21
-  completed_plans: 18
+  completed_plans: 19
  percent: 100
 ---

@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-03-30)
 ## Current Position

 Phase: 24 (search-history-branching) — EXECUTING
-Plan: 2 of 4
+Plan: 3 of 4
 Status: Ready to execute
 Last activity: 2026-04-01

@ -75,6 +75,7 @@ Progress: [██████████] 100%
 | Phase 23-brainstormer-flow P01 | 10min | 2 tasks | 2 files |
 | Phase 23-brainstormer-flow P03 | 5 | 2 tasks | 4 files |
 | Phase 24-search-history-branching P00 | 5 | 2 tasks | 9 files |
+| Phase 24-search-history-branching P01 | 12 | 2 tasks | 2 files |

 ## Accumulated Context

@ -121,6 +122,8 @@ Recent decisions affecting current work:
 - [Phase 23-brainstormer-flow]: Used useToast()/pushToast() for error toast in ChatPanel handleHandoff (custom ToastContext, not sonner)
 - [Phase 24-search-history-branching]: Used AnyPgColumn type annotation for parentConversationId self-referential FK — matches existing pattern in issues.ts, goals.ts, execution_workspaces.ts
 - [Phase 24-search-history-branching]: content_search tsvector column omitted from Drizzle schema — Postgres-generated stored column queried via raw sql`` only
+- [Phase 24-search-history-branching]: searchMessages returns empty items early when query.trim() is empty — avoids PostgreSQL error on blank tsquery
+- [Phase 24-search-history-branching]: exportConversation uses this.getConversation() to reuse notFound guard without duplicating query logic

 ### Pending Todos

@ -133,6 +136,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-04-01T22:28:30.757Z
-Stopped at: Completed 24-search-history-branching-24-00-PLAN.md
+Last session: 2026-04-01T22:33:10.661Z
+Stopped at: Completed 24-search-history-branching-24-01-PLAN.md
 Resume file: None
--- a/.planning/phases/24-search-history-branching/24-01-SUMMARY.md
+++ b/.planning/phases/24-search-history-branching/24-01-SUMMARY.md
@ -0,0 +1,118 @@
+---
+phase: 24-search-history-branching
+plan: "01"
+subsystem: api
+tags: [postgres, drizzle-orm, tsvector, fts, express, bookmarks, branching, export]
+
+requires:
+  - phase: 24-00
+    provides: "DB schema for chat_message_bookmarks, parentConversationId/branchFromMessageId in chatConversations, content_search tsvector column, searchMessagesSchema/branchConversationSchema validators, ChatMessageSearchResult/ChatBookmark types"
+
+provides:
+  - "searchMessages: tsvector FTS with ts_rank ranking, company-scoped via conversation join"
+  - "toggleBookmark: transactional insert-or-delete bookmark"
+  - "getBookmarks: paginated bookmarks with message and conversation join"
+  - "branchConversation: copies messages up to branch point into new child conversation"
+  - "listBranches: queries child conversations by parentConversationId"
+  - "exportConversation: Markdown and JSON export with agent name resolution"
+  - "Six Express route handlers: search, bookmark toggle, bookmark list, branch create, branch list, export download"
+
+affects:
+  - "24-02 (UI hooks and API client wiring)"
+  - "24-03 (UI components for search/bookmark/branch)"
+
+tech-stack:
+  added: []
+  patterns:
+    - "chatService(db) factory extended with new methods — same pattern as existing listConversations, addMessage"
+    - "tsvector FTS via raw sql`` template — content_search column is Postgres-generated stored, not in Drizzle schema"
+    - "Export route sets Content-Disposition + Content-Type headers, uses res.send(content)"
+    - "Transaction for bookmark toggle ensures atomicity of read-then-write"
+
+key-files:
+  created: []
+  modified:
+    - "server/src/services/chat.ts"
+    - "server/src/routes/chat.ts"
+
+key-decisions:
+  - "Used this.getConversation() reference in exportConversation to reuse existing notFound guard — avoids duplicate query logic"
+  - "searchMessages returns early with empty items when query is blank after trim — avoids FTS error on empty tsquery"
+
+patterns-established:
+  - "Pattern: LEFT JOIN agents ON chatMessages.agentId = agents.id for agent name resolution in export"
+  - "Pattern: branchConversation uses lte(createdAt) to include branch point message in copy"
+
+requirements-completed:
+  - CHAT-07
+  - CHAT-13
+  - CHAT-14
+  - HIST-04
+  - HIST-09
+  - HIST-10
+  - HIST-11
+  - PERF-04
+
+duration: 12min
+completed: 2026-04-01
+---
+
+# Phase 24 Plan 01: Search, Bookmarks, Branching, and Export Service + Routes Summary
+
+**Six service methods and six route handlers for full-text search (tsvector/ts_rank), bookmark toggle/list, conversation branching with message copy, and Markdown/JSON export with agent name resolution**
+
+## Performance
+
+- **Duration:** 12 min
+- **Started:** 2026-04-01T22:30:00Z
+- **Completed:** 2026-04-01T22:42:00Z
+- **Tasks:** 2
+- **Files modified:** 2
+
+## Accomplishments
+
+- searchMessages uses tsvector FTS with `plainto_tsquery` and `ts_rank` ordering, company-scoped via inner join to chatConversations
+- toggleBookmark runs in a transaction: checks for existing bookmark then either deletes (returns bookmarked: false) or inserts (returns bookmarked: true)
+- getBookmarks joins bookmarks with messages and conversations, returning full ChatBookmarkWithMessage shape
+- branchConversation copies all messages up to and including the branch point into a new child conversation with parentConversationId and branchFromMessageId set
+- listBranches queries chatConversations by parentConversationId with deletedAt IS NULL guard
+- exportConversation LEFT JOINs agents for name resolution; user messages use "You" as speaker; Markdown and JSON formats with sanitized filename slug
+- All six route handlers use assertBoard guard; search validates with ZodError 400 response; export sets Content-Disposition and Content-Type headers
+
+## Task Commits
+
+1. **Task 1: Service methods** - `5170fc3e` (feat)
+2. **Task 2: Express routes** - `9f9c9e32` (feat)
+
+## Files Created/Modified
+
+- `server/src/services/chat.ts` - Added 6 service methods: searchMessages, toggleBookmark, getBookmarks, branchConversation, listBranches, exportConversation
+- `server/src/routes/chat.ts` - Added 6 route handlers: message search, bookmark toggle, bookmark list, branch create, branch list, export download
+
+## Decisions Made
+
+- Used `this.getConversation()` inside `exportConversation` to reuse the existing notFound guard without duplicating query logic
+- `searchMessages` returns early with `{ items: [] }` when `query.trim()` is empty to avoid PostgreSQL error on an empty tsquery
+- `branchConversation` uses `lte(chatMessages.createdAt, branchMsg.createdAt)` so the branch point message itself is included in the copy
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+Pre-existing TypeScript errors in `server/src/services/plugin-host-services.ts` and plugin-related files caused the full `tsc` build to report failures, but these are unrelated to this plan's scope. Verified with targeted `tsc --noEmit | grep chat` — no errors in chat files.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- All six service methods and route handlers are implemented and TypeScript-clean
+- API client and React Query hooks (Plan 24-02) can wire against these endpoints
+- UI components (Plan 24-03) can consume the hooks built in 24-02
+
+---
+*Phase: 24-search-history-branching*
+*Completed: 2026-04-01*