spiracha 1.4.0 → 2.0.0

package/src/lib/conversation-data/cursor-adapter.ts

@@ -0,0 +1,171 @@
+import { mapWithConcurrency } from '../concurrency';
+import {
+    listCursorThreadsForGroup,
+    listCursorWorkspaceGroups,
+    readCursorThreadTranscriptWithAgentFiles,
+} from '../cursor-db';
+import type {
+    CursorBubble,
+    CursorThreadSummary,
+    CursorThreadTranscript,
+    CursorWorkspaceGroup,
+} from '../cursor-exporter-types';
+import { getCursorGlobalDbPath, resolveCursorUserDir } from '../cursor-exporter-types';
+import { cleanInlineTitle } from '../shared';
+import { createDeepLinks, createTextMessage, finalizeMessages } from './adapter-helpers';
+import { selectConversationMessages } from './message-selector';
+import { getFirstConversationPathMatch } from './path-match';
+import type {
+    ConversationAdapter,
+    ConversationDetail,
+    ConversationMessage,
+    ConversationPathMatch,
+    GetConversationOptions,
+    ListConversationsForPathOptions,
+} from './types';
+
+const CURSOR_CONVERSATION_HYDRATION_CONCURRENCY = 4;
+
+const getUserDir = (options: { locations?: { cursorUserDir?: string } }) =>
+    options.locations?.cursorUserDir ?? resolveCursorUserDir();
+
+const isWithinUpdatedWindow = (
+    thread: CursorThreadSummary,
+    options: Pick<ListConversationsForPathOptions, 'updatedAfterMs' | 'updatedBeforeMs'>,
+): boolean => {
+    const updatedAtMs = thread.lastUpdatedAtMs ?? 0;
+    if (options.updatedAfterMs !== undefined && updatedAtMs < options.updatedAfterMs) {
+        return false;
+    }
+    if (options.updatedBeforeMs !== undefined && updatedAtMs > options.updatedBeforeMs) {
+        return false;
+    }
+    return true;
+};
+
+const bubbleToMessages = (bubble: CursorBubble, order: number): ConversationMessage[] => {
+    const thinking = createTextMessage({
+        createdAtMs: bubble.createdAtMs,
+        id: `${bubble.bubbleId}:thinking`,
+        order,
+        phase: 'reasoning',
+        role: 'assistant',
+        text: bubble.thinking,
+    });
+    const text = createTextMessage({
+        createdAtMs: bubble.createdAtMs,
+        id: bubble.bubbleId,
+        order,
+        phase: bubble.kind === 'assistant' ? 'final_answer' : 'unknown',
+        role: bubble.kind === 'assistant' ? 'assistant' : bubble.kind === 'user' ? 'user' : 'unknown',
+        text: bubble.text,
+    });
+    const tool = bubble.toolCall
+        ? createTextMessage({
+              createdAtMs: bubble.createdAtMs,
+              id: `${bubble.bubbleId}:tool`,
+              metadata: { callId: bubble.toolCall.callId, status: bubble.toolCall.status },
+              order,
+              phase: bubble.toolCall.resultText ? 'tool_output' : 'tool_call',
+              role: 'tool',
+              text: bubble.toolCall.resultText ?? bubble.toolCall.argumentsText ?? bubble.toolCall.name,
+          })
+        : [];
+
+    return [...thinking, ...text, ...tool];
+};
+
+const transcriptToMessages = (transcript: CursorThreadTranscript) => {
+    return finalizeMessages(transcript.bubbles.flatMap((bubble, order) => bubbleToMessages(bubble, order)));
+};
+
+const getWorkspacePath = (group: CursorWorkspaceGroup) => {
+    return group.folders[0] ?? null;
+};
+
+const buildConversation = async (
+    thread: CursorThreadSummary,
+    group: CursorWorkspaceGroup,
+    userDir: string,
+    matches: ConversationPathMatch[],
+    options: Pick<ListConversationsForPathOptions, 'includeMessages' | 'messageSelector'>,
+): Promise<ConversationDetail> => {
+    const transcript = options.includeMessages
+        ? await readCursorThreadTranscriptWithAgentFiles(getCursorGlobalDbPath(userDir), thread.composerId, userDir)
+        : null;
+    const allMessages = transcript ? transcriptToMessages(transcript) : [];
+    const messages = options.includeMessages
+        ? selectConversationMessages(allMessages, options.messageSelector ?? 'last_final_answer')
+        : [];
+
+    return {
+        createdAtMs: thread.createdAtMs,
+        deepLinks: createDeepLinks('cursor', thread.composerId, `/cursor-threads/${thread.composerId}`),
+        id: thread.composerId,
+        matches,
+        messageCount: options.includeMessages ? allMessages.length : thread.bubbleCount,
+        messages,
+        metadata: {
+            bubbleBytes: thread.bubbleBytes,
+            bucketId: thread.bucketId,
+            mode: thread.mode,
+            transcriptDirs: thread.transcriptDirs,
+        },
+        source: 'cursor',
+        title: cleanInlineTitle(thread.name),
+        updatedAtMs: thread.lastUpdatedAtMs,
+        workspaceKey: group.key,
+        workspacePath: getWorkspacePath(group),
+    };
+};
+
+const listCursorConversationsForPath = async (options: ListConversationsForPathOptions) => {
+    const userDir = getUserDir(options);
+    const groups = await listCursorWorkspaceGroups(userDir, { updatedAfterMs: options.updatedAfterMs });
+    const candidates: { group: CursorWorkspaceGroup; match: ConversationPathMatch; thread: CursorThreadSummary }[] = [];
+
+    for (const group of groups) {
+        const match = await getFirstConversationPathMatch(options.cwd, group.folders);
+        if (!match) {
+            continue;
+        }
+        const threads = await listCursorThreadsForGroup(group, userDir, {
+            includeTranscriptDirs: false,
+            updatedAfterMs: options.updatedAfterMs,
+        });
+        for (const thread of threads) {
+            if (!isWithinUpdatedWindow(thread, options)) {
+                continue;
+            }
+
+            candidates.push({ group, match, thread });
+        }
+    }
+
+    return await mapWithConcurrency(candidates, CURSOR_CONVERSATION_HYDRATION_CONCURRENCY, ({ group, match, thread }) =>
+        buildConversation(thread, group, userDir, [match], options),
+    );
+};
+
+const getCursorConversation = async (options: GetConversationOptions): Promise<ConversationDetail | null> => {
+    const userDir = getUserDir(options);
+    const groups = await listCursorWorkspaceGroups(userDir);
+    for (const group of groups) {
+        const threads = await listCursorThreadsForGroup(group, userDir, { includeTranscriptDirs: false });
+        const thread = threads.find((entry) => entry.composerId === options.id);
+        if (thread) {
+            return buildConversation(thread, group, userDir, [], {
+                includeMessages: true,
+                messageSelector: options.messageSelector ?? 'all',
+            });
+        }
+    }
+
+    return null;
+};
+
+export const cursorConversationAdapter: ConversationAdapter = {
+    getConversation: getCursorConversation,
+    listConversationsForPath: listCursorConversationsForPath,
+    source: 'cursor',
+};

package/src/lib/conversation-data/index.ts

@@ -0,0 +1,311 @@
+import { antigravityConversationAdapter } from './antigravity-adapter';
+import { claudeCodeConversationAdapter } from './claude-code-adapter';
+import { codexConversationAdapter } from './codex-adapter';
+import { cursorConversationAdapter } from './cursor-adapter';
+import { kiroConversationAdapter } from './kiro-adapter';
+import { selectConversationMessages } from './message-selector';
+import { opencodeConversationAdapter } from './opencode-adapter';
+import { qoderConversationAdapter } from './qoder-adapter';
+import {
+    CONVERSATION_SOURCES,
+    type ConversationAdapter,
+    type ConversationMessage,
+    type ConversationMessageSelector,
+    type ConversationPage,
+    type ConversationSource,
+    type ConversationSourceInfo,
+    type GetConversationOptions,
+    type ListConversationsForPathOptions,
+    type ResolvedConversationRef,
+} from './types';
+
+export { selectConversationMessages } from './message-selector';
+export { getConversationPathMatch, normalizeConversationPath } from './path-match';
+export {
+    CONVERSATION_SOURCES,
+    type ConversationAdapter,
+    type ConversationDataLocations,
+    type ConversationDeepLinks,
+    type ConversationDetail,
+    type ConversationMessage,
+    type ConversationMessagePhase,
+    type ConversationMessageRole,
+    type ConversationMessageSelector,
+    type ConversationPage,
+    type ConversationPathMatch,
+    type ConversationSource,
+    type ConversationSourceInfo,
+    type GetConversationOptions,
+    type ListConversationsForPathOptions,
+    type ResolvedConversationRef,
+} from './types';
+
+const SOURCE_LABELS: Record<ConversationSource, string> = {
+    antigravity: 'Antigravity',
+    'claude-code': 'Claude Code',
+    codex: 'Codex',
+    cursor: 'Cursor',
+    kiro: 'Kiro',
+    opencode: 'OpenCode',
+    qoder: 'Qoder',
+};
+
+const SOURCE_INFOS: ConversationSourceInfo[] = CONVERSATION_SOURCES.map((source) => ({
+    label: SOURCE_LABELS[source],
+    source,
+}));
+
+export const isConversationSource = (value: unknown): value is ConversationSource => {
+    return typeof value === 'string' && (CONVERSATION_SOURCES as readonly string[]).includes(value);
+};
+
+const ADAPTERS: Partial<Record<ConversationSource, ConversationAdapter>> = {
+    antigravity: antigravityConversationAdapter,
+    'claude-code': claudeCodeConversationAdapter,
+    codex: codexConversationAdapter,
+    cursor: cursorConversationAdapter,
+    kiro: kiroConversationAdapter,
+    opencode: opencodeConversationAdapter,
+    qoder: qoderConversationAdapter,
+};
+
+const MAX_LIMIT = 200;
+const DEFAULT_LIMIT = 100;
+
+const getEnabledSources = (sources: ListConversationsForPathOptions['sources']): ConversationSource[] => {
+    if (!sources || sources === 'all') {
+        return SOURCE_INFOS.map((sourceInfo) => sourceInfo.source);
+    }
+
+    return sources;
+};
+
+const isAllSourcesRequest = (sources: ListConversationsForPathOptions['sources']) => !sources || sources === 'all';
+
+const getAdapter = (source: ConversationSource): ConversationAdapter | null => {
+    return ADAPTERS[source] ?? null;
+};
+
+const decodeCursor = (cursor: string | null | undefined) => {
+    if (!cursor) {
+        return 0;
+    }
+
+    const parsed = Number.parseInt(Buffer.from(cursor, 'base64url').toString('utf8'), 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+};
+
+const encodeCursor = (offset: number) => Buffer.from(String(offset), 'utf8').toString('base64url');
+
+const getLimit = (limit: number | undefined) => {
+    if (!limit || limit <= 0) {
+        return DEFAULT_LIMIT;
+    }
+
+    return Math.min(limit, MAX_LIMIT);
+};
+
+const filterByUpdatedAt = (
+    conversations: Awaited<ReturnType<ConversationAdapter['listConversationsForPath']>>,
+    options: Pick<ListConversationsForPathOptions, 'updatedAfterMs' | 'updatedBeforeMs'>,
+) => {
+    return conversations.filter((conversation) => {
+        const updatedAtMs = conversation.updatedAtMs ?? 0;
+        if (options.updatedAfterMs !== undefined && updatedAtMs < options.updatedAfterMs) {
+            return false;
+        }
+        if (options.updatedBeforeMs !== undefined && updatedAtMs > options.updatedBeforeMs) {
+            return false;
+        }
+        return true;
+    });
+};
+
+const sortConversations = (conversations: Awaited<ReturnType<ConversationAdapter['listConversationsForPath']>>) => {
+    return [...conversations].sort(
+        (left, right) =>
+            (right.updatedAtMs ?? 0) - (left.updatedAtMs ?? 0) ||
+            left.source.localeCompare(right.source) ||
+            left.id.localeCompare(right.id),
+    );
+};
+
+export const listConversationSources = async (): Promise<ConversationSourceInfo[]> => SOURCE_INFOS;
+
+const listSourceConversationsForPath = async (
+    source: ConversationSource,
+    options: ListConversationsForPathOptions,
+    ignoreSourceFailures: boolean,
+) => {
+    const adapter = getAdapter(source);
+    if (!adapter) {
+        return [];
+    }
+
+    try {
+        return await adapter.listConversationsForPath(options);
+    } catch (error) {
+        if (!ignoreSourceFailures) {
+            throw error;
+        }
+        return [];
+    }
+};
+
+export const listConversationsForPath = async (options: ListConversationsForPathOptions): Promise<ConversationPage> => {
+    const ignoreSourceFailures = isAllSourcesRequest(options.sources);
+    const conversations = (
+        await Promise.all(
+            getEnabledSources(options.sources).map((source) =>
+                listSourceConversationsForPath(source, options, ignoreSourceFailures),
+            ),
+        )
+    ).flat();
+
+    const sorted = sortConversations(filterByUpdatedAt(conversations, options));
+    const offset = decodeCursor(options.cursor);
+    const limit = getLimit(options.limit);
+    const data = sorted.slice(offset, offset + limit);
+    const nextOffset = offset + data.length;
+
+    return {
+        data,
+        meta: {
+            hasNext: nextOffset < sorted.length,
+            nextCursor: nextOffset < sorted.length ? encodeCursor(nextOffset) : null,
+        },
+    };
+};
+
+export const getConversation = async (options: GetConversationOptions) => {
+    return getAdapter(options.source)?.getConversation(options) ?? null;
+};
+
+const sourceFromSessionRoute = (segment: string): ConversationSource | null => {
+    if (segment === 'claude-code-sessions') {
+        return 'claude-code';
+    }
+    if (segment === 'kiro-sessions') {
+        return 'kiro';
+    }
+    if (segment === 'qoder-sessions') {
+        return 'qoder';
+    }
+    if (segment === 'cursor-threads') {
+        return 'cursor';
+    }
+    if (segment === 'antigravity-conversations') {
+        return 'antigravity';
+    }
+    if (segment === 'opencode-sessions') {
+        return 'opencode';
+    }
+    return null;
+};
+
+const decodeRefId = (value: string | undefined): string | null => {
+    if (!value) {
+        return null;
+    }
+
+    try {
+        const decoded = decodeURIComponent(value);
+        return decoded.trim() ? decoded : null;
+    } catch {
+        return null;
+    }
+};
+
+const refFromPathSegmentAt = (segments: string[], index: number): ResolvedConversationRef | null => {
+    const segment = segments[index];
+    const next = segments[index + 1];
+    const nextNext = segments[index + 2];
+
+    if (segment === 'threads') {
+        const id = decodeRefId(next);
+        return id ? { id, source: 'codex' } : null;
+    }
+
+    if (segment === 'conversations' && isConversationSource(next)) {
+        const id = decodeRefId(nextNext);
+        return id ? { id, source: next } : null;
+    }
+
+    const source = segment ? sourceFromSessionRoute(segment) : null;
+    if (!source) {
+        return null;
+    }
+
+    const id = decodeRefId(next);
+    return id ? { id, source } : null;
+};
+
+const refFromPathSegments = (segments: string[]): ResolvedConversationRef | null => {
+    for (let index = 0; index < segments.length - 1; index += 1) {
+        const ref = refFromPathSegmentAt(segments, index);
+        if (ref) {
+            return ref;
+        }
+    }
+
+    return null;
+};
+
+const parseUrlRef = (ref: string): ResolvedConversationRef | null => {
+    let url: URL;
+    try {
+        url = new URL(ref);
+    } catch {
+        return null;
+    }
+
+    if (url.protocol === 'codex:' && url.hostname === 'threads') {
+        const id = decodeRefId(url.pathname.replace(/^\/+/u, ''));
+        return id ? { id, source: 'codex' } : null;
+    }
+
+    if (url.protocol === 'spiracha:' && url.hostname === 'conversation') {
+        const [source, id, extra] = url.pathname.split('/').filter(Boolean);
+        const decodedId = decodeRefId(id);
+        return isConversationSource(source) && decodedId && !extra ? { id: decodedId, source } : null;
+    }
+
+    return refFromPathSegments(url.pathname.split('/').filter(Boolean));
+};
+
+export const resolveConversationRef = async (ref: string): Promise<ResolvedConversationRef | null> => {
+    const trimmed = ref.trim();
+    if (!trimmed) {
+        return null;
+    }
+
+    return parseUrlRef(trimmed);
+};
+
+export const renderConversationMarkdown = (
+    conversation: {
+        messages: ConversationMessage[];
+        title: string | null;
+    },
+    options: { messageSelector?: ConversationMessageSelector } = {},
+) => {
+    const selectedMessages = options.messageSelector
+        ? selectConversationMessages(conversation.messages, options.messageSelector)
+        : conversation.messages;
+    const title = conversation.title?.trim() || 'Conversation';
+    const roleLabels: Record<ConversationMessage['role'], string> = {
+        assistant: 'Assistant',
+        system: 'System',
+        tool: 'Tool',
+        unknown: 'Unknown',
+        user: 'User',
+    };
+    const sections = selectedMessages.map((message) => {
+        const text = message.text.trim() || '_No message content._';
+        return `## ${roleLabels[message.role]}\n\n${text}`;
+    });
+    if (sections.length === 0) {
+        sections.push('_No messages selected._');
+    }
+    return [`# ${title}`, ...sections].join('\n\n').trimEnd() + '\n';
+};

package/src/lib/conversation-data/kiro-adapter.ts

@@ -0,0 +1,140 @@
+import { listKiroSessionsForGroup, listKiroWorkspaceGroups, readKiroSessionTranscript } from '../kiro-db';
+import type {
+    KiroSessionSummary,
+    KiroSessionTranscript,
+    KiroTranscriptEntry,
+    KiroTranscriptPart,
+} from '../kiro-exporter-types';
+import { resolveKiroWorkspaceSessionsDir } from '../kiro-exporter-types';
+import { getFinalKiroAssistantMessageEntryIds, getKiroMessagePhase } from '../kiro-transcript-phase';
+import { cleanInlineTitle } from '../shared';
+import {
+    createDeepLinks,
+    createTextMessage,
+    finalizeMessages,
+    normalizeAssistantPhase,
+    normalizeRole,
+    toDateMs,
+} from './adapter-helpers';
+import { selectConversationMessages } from './message-selector';
+import { getConversationPathMatch } from './path-match';
+import type {
+    ConversationAdapter,
+    ConversationDetail,
+    ConversationMessage,
+    ConversationPathMatch,
+    GetConversationOptions,
+    ListConversationsForPathOptions,
+} from './types';
+
+const getSessionsDir = (options: { locations?: { kiroWorkspaceSessionsDir?: string } }) =>
+    options.locations?.kiroWorkspaceSessionsDir ?? resolveKiroWorkspaceSessionsDir();
+
+const partToMessages = (
+    entry: KiroTranscriptEntry,
+    part: KiroTranscriptPart,
+    partIndex: number,
+    finalEntryIds: Set<string>,
+): ConversationMessage[] => {
+    const createdAtMs = toDateMs(entry.timestamp);
+    if (entry.entryType === 'tool_call') {
+        return createTextMessage({
+            createdAtMs,
+            id: `${entry.entryId}:${partIndex}`,
+            metadata: { executionId: entry.executionId },
+            order: partIndex,
+            phase: 'tool_call',
+            role: 'tool',
+            text: part.text,
+        });
+    }
+
+    return createTextMessage({
+        createdAtMs,
+        id: `${entry.entryId}:${partIndex}`,
+        metadata: part.imageUrl ? { imageUrl: part.imageUrl } : {},
+        order: partIndex,
+        phase: normalizeAssistantPhase(getKiroMessagePhase(entry, finalEntryIds), 'unknown'),
+        role: normalizeRole(entry.role),
+        text: part.text ?? part.imageUrl,
+    });
+};
+
+const transcriptToMessages = (transcript: KiroSessionTranscript) => {
+    const finalEntryIds = getFinalKiroAssistantMessageEntryIds(transcript.entries);
+    return finalizeMessages(
+        transcript.entries.flatMap((entry) =>
+            entry.parts.flatMap((part, partIndex) => partToMessages(entry, part, partIndex, finalEntryIds)),
+        ),
+    );
+};
+
+const buildConversation = async (
+    session: KiroSessionSummary,
+    sessionsDir: string,
+    matches: ConversationPathMatch[],
+    options: Pick<ListConversationsForPathOptions, 'includeMessages' | 'messageSelector'>,
+): Promise<ConversationDetail> => {
+    const transcript = options.includeMessages ? await readKiroSessionTranscript(sessionsDir, session.sessionId) : null;
+    const allMessages = transcript ? transcriptToMessages(transcript) : [];
+    const messages = options.includeMessages
+        ? selectConversationMessages(allMessages, options.messageSelector ?? 'last_final_answer')
+        : [];
+
+    return {
+        createdAtMs: session.createdAtMs,
+        deepLinks: createDeepLinks('kiro', session.sessionId, `/kiro-sessions/${session.sessionId}`),
+        id: session.sessionId,
+        matches,
+        messageCount: options.includeMessages ? allMessages.length : session.messageCount,
+        messages,
+        metadata: {
+            defaultModelTitle: session.defaultModelTitle,
+            filePath: session.filePath,
+            model: session.selectedModel ?? session.defaultModelTitle,
+            selectedModel: session.selectedModel,
+            sessionType: session.sessionType,
+        },
+        source: 'kiro',
+        title: cleanInlineTitle(session.title),
+        updatedAtMs: session.lastActiveAtMs,
+        workspaceKey: session.workspaceKey,
+        workspacePath: session.worktree,
+    };
+};
+
+const listKiroConversationsForPath = async (options: ListConversationsForPathOptions) => {
+    const sessionsDir = getSessionsDir(options);
+    const groups = await listKiroWorkspaceGroups(sessionsDir);
+    const conversations: ConversationDetail[] = [];
+
+    for (const group of groups) {
+        const match = await getConversationPathMatch(options.cwd, group.worktree);
+        if (!match) {
+            continue;
+        }
+        const sessions = await listKiroSessionsForGroup(group.key, sessionsDir);
+        for (const session of sessions) {
+            conversations.push(await buildConversation(session, sessionsDir, [match], options));
+        }
+    }
+
+    return conversations;
+};
+
+const getKiroConversation = async (options: GetConversationOptions): Promise<ConversationDetail | null> => {
+    const sessionsDir = getSessionsDir(options);
+    const transcript = await readKiroSessionTranscript(sessionsDir, options.id);
+    return transcript
+        ? buildConversation(transcript.session, sessionsDir, [], {
+              includeMessages: true,
+              messageSelector: options.messageSelector ?? 'all',
+          })
+        : null;
+};
+
+export const kiroConversationAdapter: ConversationAdapter = {
+    getConversation: getKiroConversation,
+    listConversationsForPath: listKiroConversationsForPath,
+    source: 'kiro',
+};

package/src/lib/conversation-data/message-selector.ts

@@ -0,0 +1,37 @@
+import type { ConversationMessage, ConversationMessageSelector } from './types';
+
+const latestByOrder = (messages: ConversationMessage[]) => {
+    let latest: ConversationMessage | null = null;
+    for (const message of messages) {
+        if (!latest || message.order > latest.order) {
+            latest = message;
+        }
+    }
+    return latest;
+};
+
+const selectLastAssistantMessage = (messages: ConversationMessage[]) => {
+    return latestByOrder(messages.filter((message) => message.role === 'assistant'));
+};
+
+// Not every integration can identify final answers. In that case, API list/export defaults still
+// return the latest assistant message instead of silently omitting the conversation.
+const selectLastFinalAnswer = (messages: ConversationMessage[]) => {
+    return (
+        latestByOrder(messages.filter((message) => message.role === 'assistant' && message.phase === 'final_answer')) ??
+        selectLastAssistantMessage(messages)
+    );
+};
+
+export const selectConversationMessages = (
+    messages: ConversationMessage[],
+    selector: ConversationMessageSelector,
+): ConversationMessage[] => {
+    if (selector === 'all') {
+        return messages;
+    }
+
+    const selected =
+        selector === 'last_assistant' ? selectLastAssistantMessage(messages) : selectLastFinalAnswer(messages);
+    return selected ? [selected] : [];
+};