Nexus Dev 0ab633fc53 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-02 15:08:51 +00:00

5.3 KiB

Raw Blame History

phase

plan

subsystem

tags

requires

provides

affects

tech-stack

key-files

key-decisions

patterns-established

requirements-completed

duration

completed

24-search-history-branching

api

postgres

drizzle-orm

tsvector

fts

express

bookmarks

branching

export

phase	provides
24-00	DB schema for chat_message_bookmarks, parentConversationId/branchFromMessageId in chatConversations, content_search tsvector column, searchMessagesSchema/branchConversationSchema validators, ChatMessageSearchResult/ChatBookmark types

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

24-02 (UI hooks and API client wiring)

24-03 (UI components for search/bookmark/branch)

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

created

modified

server/src/services/chat.ts

server/src/routes/chat.ts

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

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

CHAT-07

CHAT-13

CHAT-14

HIST-04

HIST-09

HIST-10

HIST-11

PERF-04

12min

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

Task 1: Service methods - 5170fc3e (feat)
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

5.3 KiB Raw Blame History