spiracha 2.0.0 → 2.1.0

package/src/lib/concurrency.ts

@@ -23,3 +23,44 @@ export const mapWithConcurrency = async <T, TResult>(
     await Promise.all(Array.from({ length: Math.min(workerLimit, values.length) }, () => worker()));
     return results;
 };
+
+export const createConcurrencyLimiter = (limit: number) => {
+    const requestedLimit = Number.isFinite(limit) ? Math.floor(limit) : 1;
+    const workerLimit = Math.max(1, requestedLimit);
+    const queue: Array<() => void> = [];
+    let activeCount = 0;
+
+    const drain = () => {
+        if (activeCount >= workerLimit) {
+            return;
+        }
+
+        const next = queue.shift();
+        if (next) {
+            next();
+        }
+    };
+
+    return async <T>(task: () => Promise<T>): Promise<T> => {
+        await new Promise<void>((resolve) => {
+            const start = () => {
+                activeCount += 1;
+                resolve();
+            };
+
+            if (activeCount < workerLimit) {
+                start();
+                return;
+            }
+
+            queue.push(start);
+        });
+
+        try {
+            return await task();
+        } finally {
+            activeCount -= 1;
+            drain();
+        }
+    };
+};

package/src/lib/conversation-api.ts

@@ -1,6 +1,13 @@
+import { mapWithConcurrency } from './concurrency';
 import {
+    type ConversationDetail,
     type ConversationMessageSelector,
     type ConversationSource,
+    type DeleteConversationOptions,
+    type DeleteConversationsOptions,
+    deleteConversation,
+    deleteConversations,
+    type ExportConversationsZipOptions,
     type GetConversationOptions,
     getConversation,
     isConversationSource,
@@ -10,8 +17,11 @@ import {
     renderConversationMarkdown,
     resolveConversationRef,
 } from './conversation-data';
+import { createConversationMarkdownZip } from './conversation-zip-export';
 
 type ConversationApiDependencies = {
+    deleteConversation?: typeof deleteConversation;
+    deleteConversations?: typeof deleteConversations;
     getConversation?: typeof getConversation;
     listConversationSources?: typeof listConversationSources;
     listConversationsForPath?: typeof listConversationsForPath;
@@ -19,10 +29,18 @@ type ConversationApiDependencies = {
     resolveConversationRef?: typeof resolveConversationRef;
 };
 
-type ApiErrorCode = 'conversation_not_found' | 'method_not_allowed' | 'not_found' | 'validation_error';
+type ApiErrorCode =
+    | 'conversation_not_found'
+    | 'internal_error'
+    | 'method_not_allowed'
+    | 'not_found'
+    | 'unsupported_operation'
+    | 'validation_error';
 type ParseResult<T> = { error: Response } | { value: T };
 
 const MAX_CURSOR_OFFSET = 1_000_000;
+const BATCH_LOAD_CONCURRENCY = 4;
+const MAX_ID_BATCH_SIZE = 200;
 const MAX_ID_LENGTH = 2048;
 const MAX_LIMIT = 200;
 const MAX_PATH_LENGTH = 4096;
@@ -161,6 +179,16 @@ const validateTimestamp = (field: string, value: number | undefined): Response |
         : invalidFieldResponse(field, value, `\`${field}\` must be a non-negative epoch millisecond timestamp.`);
 };
 
+const validateDeleteId = (id: string): Response | null => {
+    return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u.test(id) && !id.includes('..')
+        ? null
+        : invalidFieldResponse(
+              'id',
+              id,
+              'Conversation id contains characters that are not allowed for destructive requests.',
+          );
+};
+
 const parseListLimitParam = (value: string | null): ParseResult<number | undefined> => {
     if (!value) {
         return { value: undefined };
@@ -256,6 +284,8 @@ const normalizeMeta = (meta: { hasNext: boolean; nextCursor: string | null }) =>
 });
 
 const getDeps = (dependencies: ConversationApiDependencies) => ({
+    deleteConversation: dependencies.deleteConversation ?? deleteConversation,
+    deleteConversations: dependencies.deleteConversations ?? deleteConversations,
     getConversation: dependencies.getConversation ?? getConversation,
     listConversationSources: dependencies.listConversationSources ?? listConversationSources,
     listConversationsForPath: dependencies.listConversationsForPath ?? listConversationsForPath,
@@ -319,6 +349,40 @@ const buildGetConversationOptions = (
     };
 };
 
+const buildDeleteConversationOptions = (
+    source: string | undefined,
+    id: string | undefined,
+): ParseResult<DeleteConversationOptions> => {
+    if (!source || !id) {
+        return { error: errorResponse('validation_error', 'Conversation source and id are required.', 400) };
+    }
+
+    if (!isConversationSource(source)) {
+        return { error: invalidSourceResponse(source) };
+    }
+
+    let decodedId: string;
+    try {
+        decodedId = decodeURIComponent(id);
+    } catch {
+        return { error: invalidFieldResponse('id', id, 'Conversation id must be URL encoded.') };
+    }
+    if (!decodedId.trim() || decodedId.length > MAX_ID_LENGTH) {
+        return { error: invalidFieldResponse('id', decodedId.length, 'Conversation id is invalid.') };
+    }
+    const deleteIdError = validateDeleteId(decodedId);
+    if (deleteIdError) {
+        return { error: deleteIdError };
+    }
+
+    return {
+        value: {
+            id: decodedId,
+            source,
+        },
+    };
+};
+
 const handleGetConversation = async (
     source: string | undefined,
     id: string | undefined,
@@ -360,10 +424,294 @@ const handleExportConversation = async (
         });
     }
 
-    return new Response(dependencies.renderConversationMarkdown(conversation), {
+    return new Response(
+        dependencies.renderConversationMarkdown(conversation, {
+            messageSelector: result.value.messageSelector,
+        }),
+        {
+            headers: {
+                'Cache-Control': 'no-store',
+                'Content-Type': 'text/markdown; charset=utf-8',
+                'X-Content-Type-Options': 'nosniff',
+            },
+        },
+    );
+};
+
+const handleDeleteConversation = async (
+    source: string | undefined,
+    id: string | undefined,
+    dependencies: ReturnType<typeof getDeps>,
+) => {
+    const result = buildDeleteConversationOptions(source, id);
+    if ('error' in result) {
+        return result.error;
+    }
+
+    const deleteResult = await dependencies.deleteConversation(result.value);
+    if (!deleteResult) {
+        return errorResponse(
+            'unsupported_operation',
+            `Deleting ${result.value.source} conversations is not supported by the stable API.`,
+            405,
+            {
+                source: result.value.source,
+            },
+        );
+    }
+
+    if (deleteResult.deletedIds.length === 0) {
+        return errorResponse('conversation_not_found', 'No conversation exists for that source and id.', 404, {
+            id: result.value.id,
+            source: result.value.source,
+        });
+    }
+
+    return jsonResponse({ data: deleteResult });
+};
+
+const parseJsonBody = async (request: Request): Promise<ParseResult<Record<string, unknown>>> => {
+    let body: unknown;
+    try {
+        body = await request.json();
+    } catch {
+        return { error: errorResponse('validation_error', 'Request body must be JSON.', 400) };
+    }
+
+    return isRecord(body)
+        ? { value: body }
+        : { error: errorResponse('validation_error', 'Request body must be a JSON object.', 400) };
+};
+
+const parseJsonSourceOption = (body: Record<string, unknown>): ParseResult<ConversationSource> => {
+    const sourceOption = getStringOption(body, 'source', 'source');
+    if ('error' in sourceOption) {
+        return sourceOption;
+    }
+
+    const source = sourceOption.value?.trim();
+    if (!source) {
+        return { error: errorResponse('validation_error', '`source` is required.', 400, { field: 'source' }) };
+    }
+
+    return isConversationSource(source) ? { value: source } : { error: invalidSourceResponse(source) };
+};
+
+const parseJsonIdsOption = (
+    body: Record<string, unknown>,
+    options: { destructive: boolean },
+): ParseResult<string[]> => {
+    const idsValue = getOption(body, 'ids', 'ids');
+    if (!Array.isArray(idsValue) || idsValue.length === 0) {
+        return {
+            error: invalidFieldResponse('ids', idsValue, '`ids` must be a non-empty array of explicit ids.'),
+        };
+    }
+
+    if (idsValue.length > MAX_ID_BATCH_SIZE) {
+        return {
+            error: invalidFieldResponse(
+                'ids',
+                idsValue.length,
+                `\`ids\` cannot include more than ${MAX_ID_BATCH_SIZE} ids.`,
+            ),
+        };
+    }
+
+    const ids: string[] = [];
+    const seenIds = new Set<string>();
+    for (const [index, value] of idsValue.entries()) {
+        if (typeof value !== 'string') {
+            return {
+                error: invalidFieldResponse('ids', value, `\`ids[${index}]\` must be a string.`),
+            };
+        }
+
+        const id = value.trim();
+        if (!id || id.length > MAX_ID_LENGTH) {
+            return {
+                error: invalidFieldResponse('ids', value, `\`ids[${index}]\` is invalid.`),
+            };
+        }
+
+        const deleteIdError = options.destructive ? validateDeleteId(id) : null;
+        if (deleteIdError) {
+            return { error: deleteIdError };
+        }
+
+        if (!seenIds.has(id)) {
+            seenIds.add(id);
+            ids.push(id);
+        }
+    }
+
+    return { value: ids };
+};
+
+const parseJsonExportFormat = (body: Record<string, unknown>): ParseResult<'md'> => {
+    const outputFormat = getStringOption(body, 'outputFormat', 'output_format');
+    if ('error' in outputFormat) {
+        return outputFormat;
+    }
+
+    if (outputFormat.value === undefined || outputFormat.value === 'md') {
+        return { value: 'md' };
+    }
+
+    return { error: invalidFieldResponse('output_format', outputFormat.value, '`output_format` must be "md".') };
+};
+
+const parseJsonExportMessageSelector = (body: Record<string, unknown>): ParseResult<ConversationMessageSelector> => {
+    const messageSelectorValue = getStringOption(body, 'messageSelector', 'message_selector');
+    if ('error' in messageSelectorValue) {
+        return messageSelectorValue;
+    }
+
+    return parseMessageSelector(messageSelectorValue.value ?? null, 'all');
+};
+
+const parseConversationIdSetRecord = (
+    body: Record<string, unknown>,
+    options: { destructive: boolean },
+): ParseResult<DeleteConversationsOptions> => {
+    const source = parseJsonSourceOption(body);
+    if ('error' in source) {
+        return source;
+    }
+
+    const ids = parseJsonIdsOption(body, options);
+    if ('error' in ids) {
+        return ids;
+    }
+
+    return {
+        value: {
+            ids: ids.value,
+            source: source.value,
+        },
+    };
+};
+
+const parseExportConversationsBody = async (request: Request): Promise<ParseResult<ExportConversationsZipOptions>> => {
+    const body = await parseJsonBody(request);
+    if ('error' in body) {
+        return body;
+    }
+
+    const idSet = parseConversationIdSetRecord(body.value, { destructive: false });
+    if ('error' in idSet) {
+        return idSet;
+    }
+
+    const outputFormat = parseJsonExportFormat(body.value);
+    if ('error' in outputFormat) {
+        return outputFormat;
+    }
+
+    const messageSelector = parseJsonExportMessageSelector(body.value);
+    if ('error' in messageSelector) {
+        return messageSelector;
+    }
+
+    return {
+        value: {
+            ids: idSet.value.ids,
+            messageSelector: messageSelector.value,
+            outputFormat: outputFormat.value,
+            source: idSet.value.source,
+        },
+    };
+};
+
+const handleDeleteConversations = async (request: Request, dependencies: ReturnType<typeof getDeps>) => {
+    const body = await parseJsonBody(request);
+    if ('error' in body) {
+        return body.error;
+    }
+
+    const result = parseConversationIdSetRecord(body.value, { destructive: true });
+    if ('error' in result) {
+        return result.error;
+    }
+
+    const deleteResult = await dependencies.deleteConversations(result.value);
+    if (!deleteResult) {
+        return errorResponse(
+            'unsupported_operation',
+            `Deleting ${result.value.source} conversations is not supported by the stable API.`,
+            405,
+            {
+                source: result.value.source,
+            },
+        );
+    }
+
+    if (deleteResult.deletedIds.length === 0) {
+        return errorResponse('conversation_not_found', 'No conversations exist for that source and id set.', 404, {
+            ids: result.value.ids,
+            source: result.value.source,
+        });
+    }
+
+    return jsonResponse({ data: deleteResult });
+};
+
+const getConversationZipEntry = (conversation: ConversationDetail, markdown: string) => ({
+    fallbackBaseName: `${conversation.source}-${conversation.id}`,
+    markdown,
+    title: conversation.title,
+});
+
+const handleExportConversations = async (request: Request, dependencies: ReturnType<typeof getDeps>) => {
+    const result = await parseExportConversationsBody(request);
+    if ('error' in result) {
+        return result.error;
+    }
+
+    const loaded = await mapWithConcurrency(result.value.ids, BATCH_LOAD_CONCURRENCY, async (id) => {
+        const conversation = await dependencies.getConversation({
+            id,
+            messageSelector: result.value.messageSelector,
+            source: result.value.source,
+        });
+        if (!conversation) {
+            return { entry: null, id };
+        }
+
+        return {
+            entry: getConversationZipEntry(
+                conversation,
+                dependencies.renderConversationMarkdown(conversation, {
+                    messageSelector: result.value.messageSelector,
+                }),
+            ),
+            id,
+        };
+    });
+    const missingIds = loaded.filter(({ entry }) => !entry).map(({ id }) => id);
+
+    if (missingIds.length > 0) {
+        return errorResponse(
+            'conversation_not_found',
+            'Some conversations do not exist for that source and id set.',
+            404,
+            {
+                ids: missingIds,
+                source: result.value.source,
+            },
+        );
+    }
+
+    const zip = await createConversationMarkdownZip({
+        entries: loaded.flatMap(({ entry }) => (entry ? [entry] : [])),
+        fileBaseName: `${result.value.source}-conversations-${result.value.ids.length}`,
+    });
+
+    return new Response(zip.blob, {
         headers: {
             'Cache-Control': 'no-store',
-            'Content-Type': 'text/markdown; charset=utf-8',
+            'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(zip.fileName)}`,
+            'Content-Type': zip.mimeType,
             'X-Content-Type-Options': 'nosniff',
         },
     });
@@ -685,6 +1033,24 @@ const API_ROUTES: ApiRoute[] = [
         method: 'GET',
         resource: 'conversations',
     },
+    {
+        handle: ({ dependencies, id, source }) => handleDeleteConversation(source, id, dependencies),
+        matches: ({ action, id, source }) => Boolean(source && id && !action),
+        method: 'DELETE',
+        resource: 'conversations',
+    },
+    {
+        handle: ({ dependencies, request }) => handleDeleteConversations(request, dependencies),
+        matches: ({ action, source }) => !source && action === 'delete',
+        method: 'POST',
+        resource: 'conversations',
+    },
+    {
+        handle: ({ dependencies, request }) => handleExportConversations(request, dependencies),
+        matches: ({ action, source }) => !source && action === 'export',
+        method: 'POST',
+        resource: 'conversations',
+    },
     {
         handle: ({ dependencies, url }) => handleResolve(url, dependencies),
         matches: ({ source }) => !source,
@@ -716,6 +1082,22 @@ const allowedMethodsForContext = (context: ApiRouteContext) => {
     ].sort();
 };
 
+const parseConversationApiSegments = (segments: string[], resource: string) => {
+    if (segments.length === 3) {
+        return { action: undefined, id: undefined, resource, source: undefined };
+    }
+    if (segments.length === 4 && (segments[3] === 'delete' || segments[3] === 'export')) {
+        return { action: segments[3], id: undefined, resource, source: undefined };
+    }
+    if (segments.length === 5) {
+        return { action: undefined, id: segments[4], resource, source: segments[3] };
+    }
+    if (segments.length === 6 && segments[5] === 'export') {
+        return { action: 'export', id: segments[4], resource, source: segments[3] };
+    }
+    return { action: '__invalid__', id: undefined, resource, source: undefined };
+};
+
 const parseApiSegments = (segments: string[]) => {
     if (segments.length < 3 || segments[0] !== 'api' || segments[1] !== 'v1') {
         return null;
@@ -727,23 +1109,12 @@ const parseApiSegments = (segments: string[]) => {
     }
 
     if (resource === 'conversations') {
-        if (segments.length === 3) {
-            return { action: undefined, id: undefined, resource, source: undefined };
-        }
-        if (segments.length === 5) {
-            return { action: undefined, id: segments[4], resource, source: segments[3] };
-        }
-        if (segments.length === 6 && segments[5] === 'export') {
-            return { action: 'export', id: segments[4], resource, source: segments[3] };
-        }
-        return { action: '__invalid__', id: undefined, resource, source: undefined };
-    }
-
-    if (segments.length === 3) {
-        return { action: undefined, id: undefined, resource, source: undefined };
+        return parseConversationApiSegments(segments, resource);
     }
 
-    return { action: '__invalid__', id: undefined, resource, source: undefined };
+    return segments.length === 3
+        ? { action: undefined, id: undefined, resource, source: undefined }
+        : { action: '__invalid__', id: undefined, resource, source: undefined };
 };
 
 export const handleConversationApiRequest = async (
@@ -776,7 +1147,16 @@ export const handleConversationApiRequest = async (
     const route = findRoute(context);
 
     if (route) {
-        return route.handle(context);
+        try {
+            return await route.handle(context);
+        } catch (error) {
+            console.error('[spiracha:conversation-api] request_failed', {
+                error: error instanceof Error ? error.message : String(error),
+                method: request.method,
+                pathname: url.pathname,
+            });
+            return errorResponse('internal_error', 'Conversation API request failed.', 500);
+        }
     }
 
     if (parsed.resource && API_RESOURCES.has(parsed.resource)) {

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

@@ -1,7 +1,12 @@
-import { listAntigravityConversations, readAntigravityConversationMessages } from '../antigravity-db';
+import {
+    deleteAntigravityConversation,
+    listAntigravityConversations,
+    readAntigravityConversationMessages,
+} from '../antigravity-db';
 import type { AntigravityConversation } from '../antigravity-exporter-types';
 import { resolveAntigravityRoots } from '../antigravity-exporter-types';
 import { cleanInlineTitle } from '../shared';
+import { runWithTranscriptLoadLimit } from '../transcript-load-limiter';
 import { createDeepLinks, decodeFileUri, finalizeMessages } from './adapter-helpers';
 import { selectConversationMessages } from './message-selector';
 import { getConversationPathMatch, getFirstConversationPathMatch } from './path-match';
@@ -10,6 +15,7 @@ import type {
     ConversationDetail,
     ConversationMessage,
     ConversationPathMatch,
+    DeleteConversationOptions,
     GetConversationOptions,
     ListConversationsForPathOptions,
 } from './types';
@@ -27,7 +33,11 @@ const extractAbsolutePathReferences = (text: string): string[] => {
 };
 
 const readMessages = async (conversation: AntigravityConversation) => {
-    const messages = await readAntigravityConversationMessages(conversation);
+    const messages = await runWithTranscriptLoadLimit(() => readAntigravityConversationMessages(conversation), {
+        id: conversation.conversationId,
+        path: conversation.transcriptPath ?? conversation.conversationPath ?? undefined,
+        source: 'antigravity-api',
+    });
     return finalizeMessages(
         messages.map(
             (message): ConversationMessage => ({
@@ -141,7 +151,16 @@ const getAntigravityConversation = async (options: GetConversationOptions): Prom
         : null;
 };
 
+const deleteAntigravityConversationById = async (options: DeleteConversationOptions) => {
+    const result = await deleteAntigravityConversation(getRoots(options), options.id);
+    return {
+        deletedFiles: result.deletedPaths,
+        deletedIds: result.deletedConversationIds,
+    };
+};
+
 export const antigravityConversationAdapter: ConversationAdapter = {
+    deleteConversation: deleteAntigravityConversationById,
     getConversation: getAntigravityConversation,
     listConversationsForPath: listAntigravityConversationsForPath,
     source: 'antigravity',

package/src/lib/conversation-data/claude-code-adapter.ts

@@ -1,4 +1,5 @@
 import {
+    deleteClaudeCodeSession,
     listClaudeCodeSessionsForGroup,
     listClaudeCodeWorkspaceGroups,
     readClaudeCodeSessionTranscript,
@@ -11,6 +12,7 @@ import type {
 } from '../claude-code-exporter-types';
 import { getClaudeCodeAssistantMessagePhase, resolveClaudeCodeProjectsDir } from '../claude-code-exporter-types';
 import { cleanInlineTitle } from '../shared';
+import { runWithTranscriptLoadLimit } from '../transcript-load-limiter';
 import {
     createDeepLinks,
     createTextMessage,
@@ -26,6 +28,7 @@ import type {
     ConversationDetail,
     ConversationMessage,
     ConversationPathMatch,
+    DeleteConversationOptions,
     GetConversationOptions,
     ListConversationsForPathOptions,
 } from './types';
@@ -102,9 +105,15 @@ const buildConversation = async (
     projectsDir: string,
     matches: ConversationPathMatch[],
     options: Pick<ListConversationsForPathOptions, 'includeMessages' | 'messageSelector'>,
+    loadedTranscript: ClaudeCodeSessionTranscript | null = null,
 ): Promise<ConversationDetail> => {
     const transcript = options.includeMessages
-        ? await readClaudeCodeSessionTranscript(projectsDir, session.sessionId)
+        ? (loadedTranscript ??
+          (await runWithTranscriptLoadLimit(() => readClaudeCodeSessionTranscript(projectsDir, session.sessionId), {
+              id: session.sessionId,
+              path: session.filePath,
+              source: 'claude-code-api',
+          })))
         : null;
     const allMessages = transcript ? transcriptToMessages(transcript) : [];
     const messages = options.includeMessages
@@ -157,18 +166,40 @@ const listClaudeConversationsForPath = async (
 
 const getClaudeConversation = async (options: GetConversationOptions): Promise<ConversationDetail | null> => {
     const projectsDir = getProjectsDir(options);
-    const transcript = await readClaudeCodeSessionTranscript(projectsDir, options.id);
+    const transcript = await runWithTranscriptLoadLimit(
+        () => readClaudeCodeSessionTranscript(projectsDir, options.id),
+        {
+            id: options.id,
+            path: projectsDir,
+            source: 'claude-code-api',
+        },
+    );
     if (!transcript) {
         return null;
     }
 
-    return buildConversation(transcript.session, projectsDir, [], {
-        includeMessages: true,
-        messageSelector: options.messageSelector ?? 'all',
-    });
+    return buildConversation(
+        transcript.session,
+        projectsDir,
+        [],
+        {
+            includeMessages: true,
+            messageSelector: options.messageSelector ?? 'all',
+        },
+        transcript,
+    );
+};
+
+const deleteClaudeConversation = async (options: DeleteConversationOptions) => {
+    const result = await deleteClaudeCodeSession(getProjectsDir(options), options.id);
+    return {
+        deletedFiles: result.deletedFiles,
+        deletedIds: result.deletedSessionIds,
+    };
 };
 
 export const claudeCodeConversationAdapter: ConversationAdapter = {
+    deleteConversation: deleteClaudeConversation,
     getConversation: getClaudeConversation,
     listConversationsForPath: listClaudeConversationsForPath,
     source: 'claude-code',