spiracha 1.4.0 → 2.0.0

package/apps/ui/src/lib/cursor-server.ts

@@ -0,0 +1,272 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {
+    getExportMimeType,
+    resolveUniqueExportFileBaseName,
+    sanitizeExportFileName,
+    zipExportDirectory,
+} from '@spiracha/lib/ui-export-archive';
+import { buildUiExportDownloadUrl, ensureUiExportDir } from '@spiracha/lib/ui-export-files';
+import { createServerFn } from '@tanstack/react-start';
+import { z } from 'zod';
+
+const workspaceSchema = z.object({
+    workspaceKey: z.string().min(1),
+});
+
+const threadSchema = z.object({
+    composerId: z.string().min(1),
+});
+
+const recoverSchema = z.object({
+    apply: z.boolean().default(false),
+    workspaceKey: z.string().min(1),
+});
+
+const exportSchema = z.object({
+    composerId: z.string().min(1),
+    includeCommentary: z.boolean().default(true),
+    includeMetadata: z.boolean().default(true),
+    includeTools: z.boolean().default(true),
+    outputFormat: z.enum(['md', 'txt']).default('md'),
+    zipArchive: z.boolean().default(false),
+});
+
+const exportThreadsSchema = z.object({
+    composerIds: z.array(z.string().min(1)).min(1),
+    includeCommentary: z.boolean().default(true),
+    includeMetadata: z.boolean().default(true),
+    includeTools: z.boolean().default(true),
+    outputFormat: z.enum(['md', 'txt']).default('md'),
+    zipArchive: z.boolean().default(true),
+});
+
+const deleteThreadsSchema = z.object({
+    composerIds: z.array(z.string().min(1)).min(1),
+});
+
+const ensureCursorClosedForWrite = async () => {
+    const { isCursorRunning } = await import('@spiracha/lib/cursor-recovery');
+    if (await isCursorRunning()) {
+        throw new Error(
+            'Quit Cursor before deleting. It rewrites chat history on exit, which can resurrect deleted threads.',
+        );
+    }
+};
+
+const findGroupByKey = async (workspaceKey: string) => {
+    const { listCursorWorkspaceGroups } = await import('@spiracha/lib/cursor-db');
+    const groups = await listCursorWorkspaceGroups();
+    const group = groups.find((candidate) => candidate.key === workspaceKey);
+    if (!group) {
+        throw new Error(`Cursor workspace not found: ${workspaceKey}`);
+    }
+
+    return group;
+};
+
+const toSafeExportName = (value: string) => {
+    return sanitizeExportFileName(value) || 'cursor-thread';
+};
+
+const renderCursorZipDownload = async (
+    rendered: Array<{ composerId: string; content: string }>,
+    outputFormat: 'md' | 'txt',
+) => {
+    const exportDir = await ensureUiExportDir();
+    const exportBaseName =
+        rendered.length === 1 ? `${toSafeExportName(rendered[0]!.composerId)}` : `cursor-threads-${rendered.length}`;
+    const workspaceDir = await mkdtemp(path.join(os.tmpdir(), `${exportBaseName}-`));
+    const zipPath = path.join(exportDir, `${exportBaseName}-${randomUUID()}.zip`);
+    const usedBaseNames = new Map<string, number>();
+
+    try {
+        for (const entry of rendered) {
+            const baseName = toSafeExportName(entry.composerId);
+            const fileBaseName = resolveUniqueExportFileBaseName(baseName, usedBaseNames);
+            await Bun.write(path.join(workspaceDir, `${fileBaseName}.${outputFormat}`), entry.content);
+        }
+
+        await zipExportDirectory(workspaceDir, zipPath);
+    } finally {
+        await rm(workspaceDir, { force: true, recursive: true });
+    }
+
+    return {
+        downloadUrl: buildUiExportDownloadUrl(zipPath),
+        fileName: `${exportBaseName}.zip`,
+        mimeType: 'application/zip',
+        mode: 'download_url' as const,
+    };
+};
+
+export const findCursorThreadByComposerId = async (composerId: string) => {
+    const { listCursorThreadsForGroup, listCursorWorkspaceGroups } = await import('@spiracha/lib/cursor-db');
+    for (const group of await listCursorWorkspaceGroups()) {
+        const threads = await listCursorThreadsForGroup(group, undefined, { includeTranscriptDirs: false });
+        const thread = threads.find((candidate) => candidate.composerId === composerId);
+        if (thread) {
+            return thread;
+        }
+    }
+
+    return null;
+};
+
+const renderCursorDownload = async (input: {
+    composerIds: string[];
+    includeCommentary: boolean;
+    includeMetadata: boolean;
+    includeTools: boolean;
+    outputFormat: 'md' | 'txt';
+    zipArchive: boolean;
+}) => {
+    const { readCursorThreadTranscriptWithAgentFiles } = await import('@spiracha/lib/cursor-db');
+    const { getCursorGlobalDbPath } = await import('@spiracha/lib/cursor-exporter-types');
+    const { renderCursorTranscript } = await import('@spiracha/lib/cursor-transcript');
+    const globalDbPath = getCursorGlobalDbPath();
+    const rendered = await Promise.all(
+        input.composerIds.map(async (composerId) => {
+            const transcript = await readCursorThreadTranscriptWithAgentFiles(globalDbPath, composerId);
+            if (!transcript) {
+                throw new Error(`No transcript found for thread: ${composerId}`);
+            }
+
+            const content = renderCursorTranscript(transcript, {
+                includeCommentary: input.includeCommentary,
+                includeMetadata: input.includeMetadata,
+                includeTools: input.includeTools,
+                outputFormat: input.outputFormat,
+            });
+
+            if (!content) {
+                throw new Error(`Thread has no exportable content: ${composerId}`);
+            }
+
+            return {
+                composerId,
+                content,
+            };
+        }),
+    );
+
+    if (input.zipArchive || rendered.length > 1) {
+        return renderCursorZipDownload(rendered, input.outputFormat);
+    }
+
+    if (rendered.length === 1) {
+        return {
+            content: rendered[0]!.content,
+            fileName: `${toSafeExportName(rendered[0]!.composerId)}.${input.outputFormat}`,
+            mimeType: getExportMimeType(input.outputFormat),
+            mode: 'download' as const,
+        };
+    }
+
+    throw new Error('No Cursor threads selected for export');
+};
+
+export const listCursorWorkspacesFn = createServerFn({ method: 'GET' }).handler(async () => {
+    const { listCursorWorkspaceGroups } = await import('@spiracha/lib/cursor-db');
+    return listCursorWorkspaceGroups();
+});
+
+export const listCursorThreadsFn = createServerFn({ method: 'GET' })
+    .validator(workspaceSchema)
+    .handler(async ({ data }) => {
+        const { listCursorThreadsForGroup } = await import('@spiracha/lib/cursor-db');
+        const group = await findGroupByKey(data.workspaceKey);
+        return listCursorThreadsForGroup(group, undefined, { includeTranscriptDirs: false });
+    });
+
+export const getCursorThreadDetailFn = createServerFn({ method: 'GET' })
+    .validator(threadSchema)
+    .handler(async ({ data }) => {
+        const { readCursorThreadTranscriptWithAgentFiles } = await import('@spiracha/lib/cursor-db');
+        const { getCursorGlobalDbPath } = await import('@spiracha/lib/cursor-exporter-types');
+        const thread = await findCursorThreadByComposerId(data.composerId);
+        if (!thread) {
+            throw new Error(`Cursor thread not found: ${data.composerId}`);
+        }
+
+        const transcript = await readCursorThreadTranscriptWithAgentFiles(getCursorGlobalDbPath(), data.composerId);
+        return {
+            thread,
+            transcript,
+        };
+    });
+
+export const exportCursorThreadFn = createServerFn({ method: 'POST' })
+    .validator(exportSchema)
+    .handler(async ({ data }) => {
+        return await renderCursorDownload({
+            composerIds: [data.composerId],
+            includeCommentary: data.includeCommentary,
+            includeMetadata: data.includeMetadata,
+            includeTools: data.includeTools,
+            outputFormat: data.outputFormat,
+            zipArchive: data.zipArchive,
+        });
+    });
+
+export const exportCursorThreadsFn = createServerFn({ method: 'POST' })
+    .validator(exportThreadsSchema)
+    .handler(async ({ data }) => {
+        return await renderCursorDownload({
+            composerIds: data.composerIds,
+            includeCommentary: data.includeCommentary,
+            includeMetadata: data.includeMetadata,
+            includeTools: data.includeTools,
+            outputFormat: data.outputFormat,
+            zipArchive: data.zipArchive,
+        });
+    });
+
+export const recoverCursorWorkspaceFn = createServerFn({ method: 'POST' })
+    .validator(recoverSchema)
+    .handler(async ({ data }) => {
+        const { isCursorRunning, recoverCursorWorkspaceGroup } = await import('@spiracha/lib/cursor-recovery');
+        const group = await findGroupByKey(data.workspaceKey);
+        // Cursor rewrites composer.composerHeaders on exit, so a write while it is running gets
+        // clobbered. Refuse to apply until Cursor is closed.
+        if (data.apply && (await isCursorRunning())) {
+            throw new Error('Quit Cursor before recovering. It overwrites chat history on exit, undoing the recovery.');
+        }
+
+        return recoverCursorWorkspaceGroup(group, data.apply);
+    });
+
+export const deleteCursorThreadsFn = createServerFn({ method: 'POST' })
+    .validator(deleteThreadsSchema)
+    .handler(async ({ data }) => {
+        const { collectCursorThreadsForDeletion, pruneCursorThreads } = await import('@spiracha/lib/cursor-recovery');
+        await ensureCursorClosedForWrite();
+        const threads = await collectCursorThreadsForDeletion(data.composerIds);
+        return pruneCursorThreads(threads, true);
+    });
+
+export const deleteCursorWorkspaceFn = createServerFn({ method: 'POST' })
+    .validator(workspaceSchema)
+    .handler(async ({ data }) => {
+        const { listCursorThreadsForGroup } = await import('@spiracha/lib/cursor-db');
+        const { collectCursorThreadsForDeletion, pruneCursorThreads } = await import('@spiracha/lib/cursor-recovery');
+        await ensureCursorClosedForWrite();
+        const group = await findGroupByKey(data.workspaceKey);
+        const threads = await listCursorThreadsForGroup(group, undefined, { includeTranscriptDirs: false });
+        const composerIds = threads.map((thread) => thread.composerId);
+        if (composerIds.length === 0) {
+            return {
+                bubblesDeleted: 0,
+                composerDataDeleted: 0,
+                composerIds: [],
+                headersRemoved: 0,
+                transcriptDirsRemoved: 0,
+                workspaceBucketsUpdated: 0,
+            };
+        }
+
+        const deletable = await collectCursorThreadsForDeletion(composerIds);
+        return pruneCursorThreads(deletable, true);
+    });

package/apps/ui/src/lib/cursor-transcript-events.ts

@@ -0,0 +1,229 @@
+import type { ThreadEvent, ThreadTranscriptStats } from '@spiracha/lib/codex-browser-types';
+import type { CursorBubble, CursorThreadTranscript, CursorToolCall } from '@spiracha/lib/cursor-exporter-types';
+import type { JsonValue } from '@spiracha/lib/shared';
+
+const toTimestamp = (value: number | null): string | null => {
+    if (value === null || !Number.isFinite(value)) {
+        return null;
+    }
+
+    return new Date(value).toISOString();
+};
+
+const toolCallToJson = (toolCall: CursorToolCall | null): JsonValue => {
+    if (!toolCall) {
+        return null;
+    }
+
+    return {
+        argumentsText: toolCall.argumentsText,
+        callId: toolCall.callId,
+        name: toolCall.name,
+        resultText: toolCall.resultText,
+        status: toolCall.status,
+    };
+};
+
+const buildBubbleRaw = (
+    bubble: CursorBubble,
+    eventType: string,
+    extra: Record<string, JsonValue> = {},
+): Record<string, JsonValue> => ({
+    bubbleId: bubble.bubbleId,
+    createdAtMs: bubble.createdAtMs,
+    eventType,
+    kind: bubble.kind,
+    source: 'cursor_bubble',
+    text: bubble.text,
+    thinking: bubble.thinking,
+    toolCall: toolCallToJson(bubble.toolCall),
+    ...extra,
+});
+
+const buildMessageEvent = (
+    bubble: CursorBubble,
+    sequence: number,
+    role: 'assistant' | 'user',
+    text: string,
+    phase: string | null,
+): ThreadEvent => ({
+    isHiddenByDefault: false,
+    kind: 'message',
+    memoryCitation: null,
+    model: null,
+    phase,
+    raw: buildBubbleRaw(bubble, phase === 'commentary' ? 'thinking' : 'message'),
+    role,
+    sequence,
+    text,
+    timestamp: toTimestamp(bubble.createdAtMs),
+    variant: role === 'user' ? 'user_message' : 'agent_message',
+});
+
+const buildToolCallCommand = (toolCall: CursorToolCall): string => {
+    if (!toolCall.argumentsText?.trim()) {
+        return toolCall.name;
+    }
+
+    return `${toolCall.name}\n${toolCall.argumentsText}`;
+};
+
+const buildToolCallEvent = (bubble: CursorBubble, sequence: number, toolCall: CursorToolCall): ThreadEvent => ({
+    argumentsParseFailed: false,
+    argumentsText: toolCall.argumentsText,
+    callId: toolCall.callId,
+    command: buildToolCallCommand(toolCall),
+    kind: 'tool_call',
+    name: toolCall.name,
+    raw: buildBubbleRaw(bubble, 'tool_call', {
+        argumentsText: toolCall.argumentsText,
+        callId: toolCall.callId,
+        name: toolCall.name,
+        status: toolCall.status,
+    }),
+    sequence,
+    timestamp: toTimestamp(bubble.createdAtMs),
+    workdir: null,
+});
+
+const buildToolOutputEvent = (bubble: CursorBubble, sequence: number, toolCall: CursorToolCall): ThreadEvent | null => {
+    const outputText = toolCall.resultText?.trim();
+    if (!outputText) {
+        return null;
+    }
+
+    return {
+        callId: toolCall.callId,
+        exitCode: null,
+        kind: 'tool_output',
+        outputText,
+        raw: buildBubbleRaw(bubble, 'tool_output', {
+            callId: toolCall.callId,
+            name: toolCall.name,
+            resultText: outputText,
+            status: toolCall.status,
+        }),
+        sequence,
+        summary: outputText,
+        timestamp: toTimestamp(bubble.createdAtMs),
+        wallTime: null,
+    };
+};
+
+const getAssistantFinalTextIndexes = (bubbles: CursorBubble[]) => {
+    const finalTextIndexes = new Set<number>();
+    let currentAssistantTextIndex: number | null = null;
+
+    const flushAssistantRun = () => {
+        if (currentAssistantTextIndex !== null) {
+            finalTextIndexes.add(currentAssistantTextIndex);
+            currentAssistantTextIndex = null;
+        }
+    };
+
+    bubbles.forEach((bubble, index) => {
+        if (bubble.kind !== 'assistant') {
+            flushAssistantRun();
+            return;
+        }
+
+        if (bubble.text.trim()) {
+            currentAssistantTextIndex = index;
+        }
+    });
+
+    flushAssistantRun();
+    return finalTextIndexes;
+};
+
+const cursorBubbleToThreadEvents = (
+    bubble: CursorBubble,
+    bubbleIndex: number,
+    finalTextIndexes: Set<number>,
+): ThreadEvent[] => {
+    if (bubble.kind !== 'assistant' && bubble.kind !== 'user') {
+        return [];
+    }
+
+    const baseSequence = bubbleIndex * 10;
+    const events: ThreadEvent[] = [];
+    if (bubble.kind === 'assistant' && bubble.thinking?.trim()) {
+        events.push(buildMessageEvent(bubble, baseSequence, 'assistant', bubble.thinking.trim(), 'commentary'));
+    }
+
+    if (bubble.text.trim()) {
+        const phase =
+            bubble.kind === 'assistant' ? (finalTextIndexes.has(bubbleIndex) ? 'final_answer' : 'commentary') : null;
+        events.push(buildMessageEvent(bubble, baseSequence + 1, bubble.kind, bubble.text, phase));
+    }
+
+    if (bubble.kind === 'assistant' && bubble.toolCall) {
+        events.push(buildToolCallEvent(bubble, baseSequence + 2, bubble.toolCall));
+        const output = buildToolOutputEvent(bubble, baseSequence + 3, bubble.toolCall);
+        if (output) {
+            events.push(output);
+        }
+    }
+
+    return events;
+};
+
+export const cursorTranscriptToThreadEvents = (transcript: CursorThreadTranscript): ThreadEvent[] => {
+    const finalTextIndexes = getAssistantFinalTextIndexes(transcript.bubbles);
+    return transcript.bubbles.flatMap((bubble, index) => cursorBubbleToThreadEvents(bubble, index, finalTextIndexes));
+};
+
+const updateMessageStats = (stats: ThreadTranscriptStats, event: Extract<ThreadEvent, { kind: 'message' }>) => {
+    stats.messageCount += 1;
+    if (event.role === 'assistant') {
+        stats.assistantMessageCount += 1;
+    }
+    if (event.role === 'user') {
+        stats.userMessageCount += 1;
+    }
+    if (event.phase === 'commentary') {
+        stats.commentaryCount += 1;
+    }
+    if (event.phase === 'final_answer') {
+        stats.finalAnswerCount += 1;
+    }
+};
+
+const updateCursorStats = (stats: ThreadTranscriptStats, event: ThreadEvent) => {
+    switch (event.kind) {
+        case 'message':
+            updateMessageStats(stats, event);
+            break;
+        case 'tool_call':
+            stats.toolCallCount += 1;
+            break;
+        case 'tool_output':
+            stats.toolOutputCount += 1;
+            break;
+        case 'web_search':
+            stats.webSearchEventCount += 1;
+            break;
+        default:
+            break;
+    }
+};
+
+export const getCursorThreadTranscriptStats = (events: ThreadEvent[]): ThreadTranscriptStats => {
+    const stats: ThreadTranscriptStats = {
+        assistantMessageCount: 0,
+        commentaryCount: 0,
+        execCommandCount: 0,
+        finalAnswerCount: 0,
+        messageCount: 0,
+        toolCallCount: 0,
+        toolOutputCount: 0,
+        userMessageCount: 0,
+        webSearchEventCount: 0,
+    };
+
+    for (const event of events) {
+        updateCursorStats(stats, event);
+    }
+
+    return stats;
+};

package/apps/ui/src/lib/download.ts

@@ -0,0 +1,166 @@
+type DownloadLogger = Pick<Console, 'error' | 'info' | 'warn'>;
+
+type DownloadTextOptions = {
+    createObjectUrl?: (blob: Blob) => string;
+    documentRef?: Document;
+    logger?: DownloadLogger;
+    revokeDelayMs?: number;
+    revokeObjectUrl?: (url: string) => void;
+    schedule?: (callback: () => void, delayMs: number) => void;
+};
+
+type DownloadUrlOptions = {
+    documentRef?: Document;
+    fetchImpl?: typeof fetch;
+    logger?: DownloadLogger;
+    maxAttempts?: number;
+    retryDelayMs?: number;
+    sleep?: (delayMs: number) => Promise<void>;
+};
+
+const DEFAULT_DOWNLOAD_ATTEMPTS = 6;
+const DEFAULT_DOWNLOAD_RETRY_DELAY_MS = 250;
+const DEFAULT_INLINE_REVOKE_DELAY_MS = 30000;
+
+const logDownloadEvent = (
+    logger: DownloadLogger,
+    level: keyof DownloadLogger,
+    event: string,
+    details: Record<string, unknown>,
+) => {
+    logger[level](`[spiracha:download] ${event}`, details);
+};
+
+const delay = (delayMs: number) =>
+    new Promise<void>((resolve) => {
+        window.setTimeout(resolve, delayMs);
+    });
+
+const triggerAnchorDownload = (documentRef: Document, href: string, fileName: string) => {
+    const link = documentRef.createElement('a');
+    link.href = href;
+    link.download = fileName;
+    documentRef.body.append(link);
+    link.click();
+    link.remove();
+};
+
+const isReadyStatus = (status: number) => {
+    return (status >= 200 && status < 400) || status === 405;
+};
+
+export const waitForDownloadUrlAvailability = async (
+    downloadUrl: string,
+    fileName: string,
+    {
+        fetchImpl = fetch,
+        logger = console,
+        maxAttempts = DEFAULT_DOWNLOAD_ATTEMPTS,
+        retryDelayMs = DEFAULT_DOWNLOAD_RETRY_DELAY_MS,
+        sleep = delay,
+    }: Omit<DownloadUrlOptions, 'documentRef'> = {},
+) => {
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const response = await fetchImpl(downloadUrl, {
+                cache: 'no-store',
+                method: 'HEAD',
+            });
+
+            if (isReadyStatus(response.status)) {
+                logDownloadEvent(logger, 'info', 'url_ready', {
+                    attempt,
+                    downloadUrl,
+                    fileName,
+                    status: response.status,
+                });
+                return;
+            }
+
+            logDownloadEvent(logger, 'warn', 'url_not_ready', {
+                attempt,
+                downloadUrl,
+                fileName,
+                status: response.status,
+            });
+        } catch (error) {
+            logDownloadEvent(logger, 'warn', 'url_probe_failed', {
+                attempt,
+                downloadUrl,
+                error: error instanceof Error ? error.message : String(error),
+                fileName,
+            });
+        }
+
+        if (attempt < maxAttempts) {
+            await sleep(retryDelayMs);
+        }
+    }
+
+    throw new Error(`Download file was not available after ${maxAttempts} attempts: ${fileName}`);
+};
+
+export const downloadUrlFile = async (
+    fileName: string,
+    downloadUrl: string,
+    {
+        documentRef = document,
+        fetchImpl = fetch,
+        logger = console,
+        maxAttempts = DEFAULT_DOWNLOAD_ATTEMPTS,
+        retryDelayMs = DEFAULT_DOWNLOAD_RETRY_DELAY_MS,
+        sleep = delay,
+    }: DownloadUrlOptions = {},
+) => {
+    logDownloadEvent(logger, 'info', 'start', {
+        downloadUrl,
+        fileName,
+    });
+
+    await waitForDownloadUrlAvailability(downloadUrl, fileName, {
+        fetchImpl,
+        logger,
+        maxAttempts,
+        retryDelayMs,
+        sleep,
+    });
+
+    triggerAnchorDownload(documentRef, downloadUrl, fileName);
+    logDownloadEvent(logger, 'info', 'triggered', {
+        downloadUrl,
+        fileName,
+    });
+};
+
+export const downloadTextFile = (
+    fileName: string,
+    content: string,
+    mimeType: string,
+    {
+        createObjectUrl = (blob) => URL.createObjectURL(blob),
+        documentRef = document,
+        logger = console,
+        revokeDelayMs = DEFAULT_INLINE_REVOKE_DELAY_MS,
+        revokeObjectUrl = (url) => URL.revokeObjectURL(url),
+        schedule = (callback, delayMs) => {
+            window.setTimeout(callback, delayMs);
+        },
+    }: DownloadTextOptions = {},
+) => {
+    logDownloadEvent(logger, 'info', 'inline_start', {
+        fileName,
+        mimeType,
+        sizeBytes: content.length,
+    });
+
+    const blob = new Blob([content], { type: mimeType });
+    const url = createObjectUrl(blob);
+    triggerAnchorDownload(documentRef, url, fileName);
+    schedule(() => revokeObjectUrl(url), revokeDelayMs);
+
+    logDownloadEvent(logger, 'info', 'inline_triggered', {
+        fileName,
+        mimeType,
+        sizeBytes: content.length,
+    });
+};