spiracha 1.5.0 → 2.1.0

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

@@ -0,0 +1,386 @@
+import { mapWithConcurrency } from '../concurrency';
+import { antigravityConversationAdapter } from './antigravity-adapter';
+import { claudeCodeConversationAdapter } from './claude-code-adapter';
+import { codexConversationAdapter } from './codex-adapter';
+import { cursorConversationAdapter } from './cursor-adapter';
+import { grokConversationAdapter } from './grok-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 DeleteConversationItemResult,
+    type DeleteConversationOptions,
+    type DeleteConversationResult,
+    type DeleteConversationsOptions,
+    type DeleteConversationsResult,
+    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 ConversationIdSetOptions,
+    type ConversationMessage,
+    type ConversationMessagePhase,
+    type ConversationMessageRole,
+    type ConversationMessageSelector,
+    type ConversationPage,
+    type ConversationPathMatch,
+    type ConversationSource,
+    type ConversationSourceInfo,
+    type ConversationZipDownload,
+    type DeleteConversationItemResult,
+    type DeleteConversationOptions,
+    type DeleteConversationResult,
+    type DeleteConversationsOptions,
+    type DeleteConversationsResult,
+    type ExportConversationsZipOptions,
+    type GetConversationOptions,
+    type ListConversationsForPathOptions,
+    type ResolvedConversationRef,
+} from './types';
+
+const SOURCE_LABELS: Record<ConversationSource, string> = {
+    antigravity: 'Antigravity',
+    'claude-code': 'Claude Code',
+    codex: 'Codex',
+    cursor: 'Cursor',
+    grok: 'Grok',
+    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,
+    grok: grokConversationAdapter,
+    kiro: kiroConversationAdapter,
+    opencode: opencodeConversationAdapter,
+    qoder: qoderConversationAdapter,
+};
+
+const MAX_LIMIT = 200;
+const DEFAULT_LIMIT = 100;
+const DELETE_CONCURRENCY_BY_SOURCE: Record<ConversationSource, number> = {
+    antigravity: 1,
+    'claude-code': 4,
+    codex: 1,
+    cursor: 1,
+    grok: 1,
+    kiro: 1,
+    opencode: 2,
+    qoder: 1,
+};
+
+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;
+};
+
+export const deleteConversation = async (
+    options: DeleteConversationOptions,
+): Promise<DeleteConversationResult | null> => {
+    return (await getAdapter(options.source)?.deleteConversation?.(options)) ?? null;
+};
+
+export const deleteConversations = async (
+    options: DeleteConversationsOptions,
+): Promise<DeleteConversationsResult | null> => {
+    const adapter = getAdapter(options.source);
+    if (!adapter?.deleteConversation) {
+        return null;
+    }
+    const deleteAdapterConversation = adapter.deleteConversation;
+
+    const rawResults = await mapWithConcurrency(
+        options.ids,
+        DELETE_CONCURRENCY_BY_SOURCE[options.source],
+        async (id) => ({
+            id,
+            result: await deleteAdapterConversation({
+                id,
+                locations: options.locations,
+                source: options.source,
+            }),
+        }),
+    );
+    const deletedIdSet = new Set(rawResults.flatMap(({ result }) => result.deletedIds));
+    const results: DeleteConversationItemResult[] = rawResults.map(({ id, result }) => ({
+        deleted: result.deletedIds.length > 0 || deletedIdSet.has(id),
+        deletedFiles: result.deletedFiles,
+        deletedIds: result.deletedIds,
+        id,
+    }));
+
+    return {
+        deletedFiles: [...new Set(results.flatMap((result) => result.deletedFiles))],
+        deletedIds: [...deletedIdSet],
+        missingIds: results.filter((result) => !result.deleted).map((result) => result.id),
+        results,
+    };
+};
+
+const sourceFromSessionRoute = (segment: string): ConversationSource | null => {
+    if (segment === 'claude-code-sessions') {
+        return 'claude-code';
+    }
+    if (segment === 'grok-sessions') {
+        return 'grok';
+    }
+    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,174 @@
+import {
+    deleteKiroSession,
+    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 { runWithTranscriptLoadLimit } from '../transcript-load-limiter';
+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,
+    DeleteConversationOptions,
+    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'>,
+    loadedTranscript: KiroSessionTranscript | null = null,
+): Promise<ConversationDetail> => {
+    const transcript = options.includeMessages
+        ? (loadedTranscript ??
+          (await runWithTranscriptLoadLimit(() => readKiroSessionTranscript(sessionsDir, session.sessionId), {
+              id: session.sessionId,
+              path: session.filePath,
+              source: 'kiro-api',
+          })))
+        : 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 runWithTranscriptLoadLimit(() => readKiroSessionTranscript(sessionsDir, options.id), {
+        id: options.id,
+        path: sessionsDir,
+        source: 'kiro-api',
+    });
+    return transcript
+        ? buildConversation(
+              transcript.session,
+              sessionsDir,
+              [],
+              {
+                  includeMessages: true,
+                  messageSelector: options.messageSelector ?? 'all',
+              },
+              transcript,
+          )
+        : null;
+};
+
+const deleteKiroConversation = async (options: DeleteConversationOptions) => {
+    const result = await deleteKiroSession(getSessionsDir(options), options.id);
+    return {
+        deletedFiles: result.deletedFiles,
+        deletedIds: result.deletedSessionIds,
+    };
+};
+
+export const kiroConversationAdapter: ConversationAdapter = {
+    deleteConversation: deleteKiroConversation,
+    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] : [];
+};