feat(timeline): implement TimelineService for building and formatting timeline items
- Extracted timeline-related functionality from mcp-server.ts to a dedicated TimelineService class. - Added methods to build, filter, and format timeline items based on observations, sessions, and prompts. - Introduced interfaces for TimelineItem and TimelineData to standardize data structures. - Implemented sorting and grouping of timeline items by date, with markdown formatting for output. - Included utility methods for date and time formatting, as well as token estimation.
This commit is contained in:
Alex Newman
@@ -0,0 +1,270 @@
|
||||
/**
|
||||
* TimelineService - Handles timeline building, filtering, and formatting
|
||||
* Extracted from mcp-server.ts to follow worker service organization pattern
|
||||
*/
|
||||
|
||||
import { ObservationSearchResult, SessionSummarySearchResult, UserPromptSearchResult } from '../sqlite/types.js';
|
||||
|
||||
/**
|
||||
* Timeline item for unified chronological display
|
||||
*/
|
||||
export interface TimelineItem {
|
||||
type: 'observation' | 'session' | 'prompt';
|
||||
data: ObservationSearchResult | SessionSummarySearchResult | UserPromptSearchResult;
|
||||
epoch: number;
|
||||
}
|
||||
|
||||
export interface TimelineData {
|
||||
observations: ObservationSearchResult[];
|
||||
sessions: SessionSummarySearchResult[];
|
||||
prompts: UserPromptSearchResult[];
|
||||
}
|
||||
|
||||
export class TimelineService {
|
||||
/**
|
||||
* Build timeline items from observations, sessions, and prompts
|
||||
*/
|
||||
buildTimeline(data: TimelineData): TimelineItem[] {
|
||||
const items: TimelineItem[] = [
|
||||
...data.observations.map(obs => ({ type: 'observation' as const, data: obs, epoch: obs.created_at_epoch })),
|
||||
...data.sessions.map(sess => ({ type: 'session' as const, data: sess, epoch: sess.created_at_epoch })),
|
||||
...data.prompts.map(prompt => ({ type: 'prompt' as const, data: prompt, epoch: prompt.created_at_epoch }))
|
||||
];
|
||||
items.sort((a, b) => a.epoch - b.epoch);
|
||||
return items;
|
||||
}
|
||||
|
||||
/**
|
||||
* Filter timeline items to respect depth_before/depth_after window around anchor
|
||||
*/
|
||||
filterByDepth(
|
||||
items: TimelineItem[],
|
||||
anchorId: number | string,
|
||||
anchorEpoch: number,
|
||||
depth_before: number,
|
||||
depth_after: number
|
||||
): TimelineItem[] {
|
||||
if (items.length === 0) return items;
|
||||
|
||||
let anchorIndex = -1;
|
||||
if (typeof anchorId === 'number') {
|
||||
anchorIndex = items.findIndex(item => item.type === 'observation' && (item.data as ObservationSearchResult).id === anchorId);
|
||||
} else if (typeof anchorId === 'string' && anchorId.startsWith('S')) {
|
||||
const sessionNum = parseInt(anchorId.slice(1), 10);
|
||||
anchorIndex = items.findIndex(item => item.type === 'session' && (item.data as SessionSummarySearchResult).id === sessionNum);
|
||||
} else {
|
||||
// Timestamp anchor - find closest item
|
||||
anchorIndex = items.findIndex(item => item.epoch >= anchorEpoch);
|
||||
if (anchorIndex === -1) anchorIndex = items.length - 1;
|
||||
}
|
||||
|
||||
if (anchorIndex === -1) return items;
|
||||
|
||||
const startIndex = Math.max(0, anchorIndex - depth_before);
|
||||
const endIndex = Math.min(items.length, anchorIndex + depth_after + 1);
|
||||
return items.slice(startIndex, endIndex);
|
||||
}
|
||||
|
||||
/**
|
||||
* Format timeline items as markdown with grouped days and tables
|
||||
*/
|
||||
formatTimeline(
|
||||
items: TimelineItem[],
|
||||
anchorId: number | string | null,
|
||||
query?: string,
|
||||
depth_before?: number,
|
||||
depth_after?: number
|
||||
): string {
|
||||
if (items.length === 0) {
|
||||
return query
|
||||
? `Found observation matching "${query}", but no timeline context available.`
|
||||
: 'No timeline items found';
|
||||
}
|
||||
|
||||
const lines: string[] = [];
|
||||
|
||||
// Header
|
||||
if (query && anchorId) {
|
||||
const anchorObs = items.find(item => item.type === 'observation' && (item.data as ObservationSearchResult).id === anchorId);
|
||||
const anchorTitle = anchorObs ? ((anchorObs.data as ObservationSearchResult).title || 'Untitled') : 'Unknown';
|
||||
lines.push(`# Timeline for query: "${query}"`);
|
||||
lines.push(`**Anchor:** Observation #${anchorId} - ${anchorTitle}`);
|
||||
} else if (anchorId) {
|
||||
lines.push(`# Timeline around anchor: ${anchorId}`);
|
||||
} else {
|
||||
lines.push(`# Timeline`);
|
||||
}
|
||||
|
||||
if (depth_before !== undefined && depth_after !== undefined) {
|
||||
lines.push(`**Window:** ${depth_before} records before → ${depth_after} records after | **Items:** ${items.length}`);
|
||||
} else {
|
||||
lines.push(`**Items:** ${items.length}`);
|
||||
}
|
||||
lines.push('');
|
||||
|
||||
// Legend
|
||||
lines.push(`**Legend:** 🎯 session-request | 🔴 bugfix | 🟣 feature | 🔄 refactor | ✅ change | 🔵 discovery | 🧠 decision`);
|
||||
lines.push('');
|
||||
|
||||
// Group by day
|
||||
const dayMap = new Map<string, TimelineItem[]>();
|
||||
for (const item of items) {
|
||||
const day = this.formatDate(item.epoch);
|
||||
if (!dayMap.has(day)) {
|
||||
dayMap.set(day, []);
|
||||
}
|
||||
dayMap.get(day)!.push(item);
|
||||
}
|
||||
|
||||
// Sort days chronologically
|
||||
const sortedDays = Array.from(dayMap.entries()).sort((a, b) => {
|
||||
const aDate = new Date(a[0]).getTime();
|
||||
const bDate = new Date(b[0]).getTime();
|
||||
return aDate - bDate;
|
||||
});
|
||||
|
||||
// Render each day
|
||||
for (const [day, dayItems] of sortedDays) {
|
||||
lines.push(`### ${day}`);
|
||||
lines.push('');
|
||||
|
||||
let currentFile: string | null = null;
|
||||
let lastTime = '';
|
||||
let tableOpen = false;
|
||||
|
||||
for (const item of dayItems) {
|
||||
const isAnchor = (
|
||||
(typeof anchorId === 'number' && item.type === 'observation' && (item.data as ObservationSearchResult).id === anchorId) ||
|
||||
(typeof anchorId === 'string' && anchorId.startsWith('S') && item.type === 'session' && `S${(item.data as SessionSummarySearchResult).id}` === anchorId)
|
||||
);
|
||||
|
||||
if (item.type === 'session') {
|
||||
if (tableOpen) {
|
||||
lines.push('');
|
||||
tableOpen = false;
|
||||
currentFile = null;
|
||||
lastTime = '';
|
||||
}
|
||||
|
||||
const sess = item.data as SessionSummarySearchResult;
|
||||
const title = sess.request || 'Session summary';
|
||||
const link = `claude-mem://session-summary/${sess.id}`;
|
||||
const marker = isAnchor ? ' ← **ANCHOR**' : '';
|
||||
|
||||
lines.push(`**🎯 #S${sess.id}** ${title} (${this.formatDateTime(item.epoch)}) [→](${link})${marker}`);
|
||||
lines.push('');
|
||||
} else if (item.type === 'prompt') {
|
||||
if (tableOpen) {
|
||||
lines.push('');
|
||||
tableOpen = false;
|
||||
currentFile = null;
|
||||
lastTime = '';
|
||||
}
|
||||
|
||||
const prompt = item.data as UserPromptSearchResult;
|
||||
const truncated = prompt.prompt_text.length > 100 ? prompt.prompt_text.substring(0, 100) + '...' : prompt.prompt_text;
|
||||
|
||||
lines.push(`**💬 User Prompt #${prompt.prompt_number}** (${this.formatDateTime(item.epoch)})`);
|
||||
lines.push(`> ${truncated}`);
|
||||
lines.push('');
|
||||
} else if (item.type === 'observation') {
|
||||
const obs = item.data as ObservationSearchResult;
|
||||
const file = 'General';
|
||||
|
||||
if (file !== currentFile) {
|
||||
if (tableOpen) {
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push(`**${file}**`);
|
||||
lines.push(`| ID | Time | T | Title | Tokens |`);
|
||||
lines.push(`|----|------|---|-------|--------|`);
|
||||
|
||||
currentFile = file;
|
||||
tableOpen = true;
|
||||
lastTime = '';
|
||||
}
|
||||
|
||||
const icon = this.getTypeIcon(obs.type);
|
||||
const time = this.formatTime(item.epoch);
|
||||
const title = obs.title || 'Untitled';
|
||||
const tokens = this.estimateTokens(obs.narrative);
|
||||
|
||||
const showTime = time !== lastTime;
|
||||
const timeDisplay = showTime ? time : '″';
|
||||
lastTime = time;
|
||||
|
||||
const anchorMarker = isAnchor ? ' ← **ANCHOR**' : '';
|
||||
lines.push(`| #${obs.id} | ${timeDisplay} | ${icon} | ${title}${anchorMarker} | ~${tokens} |`);
|
||||
}
|
||||
}
|
||||
|
||||
if (tableOpen) {
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get icon for observation type
|
||||
*/
|
||||
private getTypeIcon(type: string): string {
|
||||
switch (type) {
|
||||
case 'bugfix': return '🔴';
|
||||
case 'feature': return '🟣';
|
||||
case 'refactor': return '🔄';
|
||||
case 'change': return '✅';
|
||||
case 'discovery': return '🔵';
|
||||
case 'decision': return '🧠';
|
||||
default: return '•';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Format date for grouping (e.g., "Dec 7, 2025")
|
||||
*/
|
||||
private formatDate(epochMs: number): string {
|
||||
const date = new Date(epochMs);
|
||||
return date.toLocaleString('en-US', {
|
||||
month: 'short',
|
||||
day: 'numeric',
|
||||
year: 'numeric'
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Format time (e.g., "6:30 PM")
|
||||
*/
|
||||
private formatTime(epochMs: number): string {
|
||||
const date = new Date(epochMs);
|
||||
return date.toLocaleString('en-US', {
|
||||
hour: 'numeric',
|
||||
minute: '2-digit',
|
||||
hour12: true
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Format date and time (e.g., "Dec 7, 6:30 PM")
|
||||
*/
|
||||
private formatDateTime(epochMs: number): string {
|
||||
const date = new Date(epochMs);
|
||||
return date.toLocaleString('en-US', {
|
||||
month: 'short',
|
||||
day: 'numeric',
|
||||
hour: 'numeric',
|
||||
minute: '2-digit',
|
||||
hour12: true
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Estimate tokens from text length (~4 chars per token)
|
||||
*/
|
||||
private estimateTokens(text: string | null): number {
|
||||
if (!text) return 0;
|
||||
return Math.ceil(text.length / 4);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user