spiracha 2.0.0 → 2.2.0

package/src/lib/conversation-api.ts

@@ -1,6 +1,14 @@
+import path from 'node:path';
+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 +18,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 +30,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;
@@ -80,10 +99,14 @@ const parseSources = (value: string | null): ParseResult<ConversationSource[] |
         return { value: 'all' };
     }
 
-    const sources = value
-        .split(',')
-        .map((source) => source.trim())
-        .filter(Boolean);
+    const sources = [
+        ...new Set(
+            value
+                .split(',')
+                .map((source) => source.trim())
+                .filter(Boolean),
+        ),
+    ];
     const invalidSource = sources.find((source) => !isConversationSource(source));
 
     return invalidSource ? { error: invalidSourceResponse(invalidSource) } : { value: sources as ConversationSource[] };
@@ -151,6 +174,9 @@ const validatePathLength = (field: string, value: string): Response | null => {
         : invalidFieldResponse(field, value.length, `\`${field}\` is too long.`);
 };
 
+const validateAbsoluteCwd = (cwd: string): Response | null =>
+    path.isAbsolute(cwd) ? null : invalidFieldResponse('cwd', cwd, '`cwd` must be an absolute path.');
+
 const validateTimestamp = (field: string, value: number | undefined): Response | null => {
     if (value === undefined) {
         return null;
@@ -161,6 +187,12 @@ const validateTimestamp = (field: string, value: number | undefined): Response |
         : invalidFieldResponse(field, value, `\`${field}\` must be a non-negative epoch millisecond timestamp.`);
 };
 
+const validateConversationId = (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 by the stable API.');
+};
+
 const parseListLimitParam = (value: string | null): ParseResult<number | undefined> => {
     if (!value) {
         return { value: undefined };
@@ -204,6 +236,10 @@ const buildListOptions = (url: URL): ParseResult<ListConversationsForPathOptions
     if (cwdLengthError) {
         return { error: cwdLengthError };
     }
+    const cwdAbsoluteError = validateAbsoluteCwd(cwd);
+    if (cwdAbsoluteError) {
+        return { error: cwdAbsoluteError };
+    }
 
     const cursor = url.searchParams.get('cursor');
     const cursorError = validateCursor(cursor);
@@ -251,11 +287,13 @@ const buildListOptions = (url: URL): ParseResult<ListConversationsForPathOptions
 };
 
 const normalizeMeta = (meta: { hasNext: boolean; nextCursor: string | null }) => ({
-    hasNext: meta.hasNext,
+    has_next: meta.hasNext,
     next_cursor: meta.nextCursor,
 });
 
 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 +357,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 idError = validateConversationId(decodedId);
+    if (idError) {
+        return { error: idError };
+    }
+
+    return {
+        value: {
+            id: decodedId,
+            source,
+        },
+    };
+};
+
 const handleGetConversation = async (
     source: string | undefined,
     id: string | undefined,
@@ -360,10 +432,288 @@ 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>): 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 idError = validateConversationId(id);
+        if (idError) {
+            return { error: idError };
+        }
+
+        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>): ParseResult<DeleteConversationsOptions> => {
+    const source = parseJsonSourceOption(body);
+    if ('error' in source) {
+        return source;
+    }
+
+    const ids = parseJsonIdsOption(body);
+    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);
+    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);
+    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',
         },
     });
@@ -497,8 +847,8 @@ const parseJsonCwd = (body: Record<string, unknown>): ParseResult<string> => {
         return { error: errorResponse('validation_error', '`cwd` is required.', 400, { field: 'cwd' }) };
     }
 
-    const cwdLengthError = validatePathLength('cwd', cwd);
-    return cwdLengthError ? { error: cwdLengthError } : { value: cwd };
+    const cwdError = validatePathLength('cwd', cwd) ?? validateAbsoluteCwd(cwd);
+    return cwdError ? { error: cwdError } : { value: cwd };
 };
 
 const parseJsonCursor = (body: Record<string, unknown>): ParseResult<string | null> => {
@@ -606,6 +956,7 @@ const validateListQueryOptions = (options: ListConversationsForPathOptions): Res
 
     return (
         validatePathLength('cwd', options.cwd) ??
+        validateAbsoluteCwd(options.cwd) ??
         validateCursor(options.cursor) ??
         validateLimit(options.limit) ??
         validateTimestamp('updated_after_ms', options.updatedAfterMs) ??
@@ -669,7 +1020,7 @@ const API_ROUTES: ApiRoute[] = [
     },
     {
         handle: ({ dependencies, url }) => handleListConversations(url, dependencies),
-        matches: ({ source }) => !source,
+        matches: ({ action, source }) => !source && !action,
         method: 'GET',
         resource: 'conversations',
     },
@@ -685,6 +1036,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 +1085,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 +1112,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 +1150,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/adapter-helpers.ts

@@ -4,8 +4,23 @@ import type {
     ConversationMessagePhase,
     ConversationMessageRole,
     ConversationSource,
+    ListConversationsForPathOptions,
 } from './types';
 
+export const isWithinUpdatedWindow = (
+    updatedAtMs: number | null | undefined,
+    options: Pick<ListConversationsForPathOptions, 'updatedAfterMs' | 'updatedBeforeMs'>,
+) => {
+    const comparableUpdatedAtMs = updatedAtMs ?? 0;
+    if (options.updatedAfterMs !== undefined && comparableUpdatedAtMs < options.updatedAfterMs) {
+        return false;
+    }
+    if (options.updatedBeforeMs !== undefined && comparableUpdatedAtMs > options.updatedBeforeMs) {
+        return false;
+    }
+    return true;
+};
+
 export const toDateMs = (value: string | number | null | undefined): number | null => {
     if (typeof value === 'number') {
         return Number.isFinite(value) ? value : null;
@@ -36,8 +51,12 @@ export const decodeFileUri = (value: string | null | undefined): string | null =
         }
         return pathname.replace(/^\/([A-Za-z]:)/u, '$1');
     } catch {
-        const pathValue = decodeURIComponent(value.slice('file://'.length));
-        return pathValue.replace(/^\/([A-Za-z]:)/u, '$1');
+        const rawPathValue = value.slice('file://'.length);
+        try {
+            return decodeURIComponent(rawPathValue).replace(/^\/([A-Za-z]:)/u, '$1');
+        } catch {
+            return rawPathValue.replace(/^\/([A-Za-z]:)/u, '$1');
+        }
     }
 };
 
@@ -48,10 +67,13 @@ export const createDeepLinks = (
     native: string | null = null,
 ): ConversationDeepLinks => ({
     native,
-    spiracha: `spiracha://conversation/${source}/${id}`,
+    spiracha: `spiracha://conversation/${source}/${encodeURIComponent(id)}`,
     ui: uiPath,
 });
 
+export const createConversationUiPath = (routeSegment: string, id: string) =>
+    `/${routeSegment}/${encodeURIComponent(id)}`;
+
 export const normalizeRole = (role: string | null | undefined): ConversationMessageRole => {
     if (role === 'assistant' || role === 'system' || role === 'tool' || role === 'user') {
         return role;