spiracha 2.0.0 → 2.2.0

package/apps/ui/vite.config.ts

@@ -1,12 +1,17 @@
 import { createReadStream } from 'node:fs';
-import { access, constants } from 'node:fs/promises';
 import path from 'node:path';
 import tailwindcss from '@tailwindcss/vite';
 import { devtools } from '@tanstack/devtools-vite';
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
 import viteReact from '@vitejs/plugin-react';
 import { defineConfig, type Plugin } from 'vite';
-import { buildUiExportContentDisposition, resolveUiExportFilePathFromRequestPath } from '../../src/lib/ui-export-files';
+import {
+    buildUiExportContentDisposition,
+    resolveReadableUiExportFileFromRequestPath,
+    UI_EXPORT_URL_PREFIX,
+} from '../../src/lib/ui-export-files';
+
+const uiRoot = __dirname;
 
 const getExportContentType = (filePath: string) => {
     if (filePath.endsWith('.zip')) {
@@ -33,17 +38,14 @@ const spirachaExportFiles = (): Plugin => {
                     return;
                 }
 
-                const exportFilePath = resolveUiExportFilePathFromRequestPath(
-                    new URL(req.url, 'http://spiracha.local').pathname,
-                );
-                if (!exportFilePath) {
+                const pathname = new URL(req.url, 'http://spiracha.local').pathname;
+                if (!pathname.startsWith(UI_EXPORT_URL_PREFIX)) {
                     next();
                     return;
                 }
 
-                try {
-                    await access(exportFilePath, constants.R_OK);
-                } catch {
+                const exportFilePath = await resolveReadableUiExportFileFromRequestPath(pathname);
+                if (!exportFilePath) {
                     res.statusCode = 404;
                     res.end('Not Found');
                     return;
@@ -59,7 +61,14 @@ const spirachaExportFiles = (): Plugin => {
                     return;
                 }
 
-                createReadStream(exportFilePath).pipe(res);
+                const stream = createReadStream(exportFilePath);
+                stream.once('error', () => {
+                    if (!res.headersSent) {
+                        res.statusCode = 500;
+                    }
+                    res.end('Internal Server Error');
+                });
+                stream.pipe(res);
             });
         },
         name: 'spiracha-export-files',
@@ -70,13 +79,14 @@ const config = defineConfig({
     plugins: [spirachaExportFiles(), devtools(), tailwindcss(), tanstackStart(), viteReact()],
     resolve: {
         alias: {
-            '@spiracha': path.resolve(__dirname, '..', '..', 'src'),
+            '@spiracha': path.resolve(uiRoot, '..', '..', 'src'),
         },
         tsconfigPaths: true,
     },
+    root: uiRoot,
     server: {
         fs: {
-            allow: [path.resolve(__dirname, '..', '..')],
+            allow: [path.resolve(uiRoot, '..', '..')],
         },
     },
 });

package/bin/spiracha.ts

@@ -14,6 +14,33 @@ export const buildSpirachaDevServerCommand = (packageRoot = resolveSpirachaPacka
     cwd: path.join(packageRoot, 'apps', 'ui'),
 });
 
+type SpirachaChildProcess = {
+    exited: Promise<number>;
+    kill: (signal?: NodeJS.Signals | number) => void;
+};
+
+type SpirachaSignalEmitter = {
+    off: (event: NodeJS.Signals, listener: () => void) => unknown;
+    on: (event: NodeJS.Signals, listener: () => void) => unknown;
+};
+
+export const waitForSpirachaDevServer = async (
+    child: SpirachaChildProcess,
+    signalEmitter: SpirachaSignalEmitter = process,
+): Promise<number> => {
+    const forwardSigint = () => child.kill('SIGINT');
+    const forwardSigterm = () => child.kill('SIGTERM');
+    signalEmitter.on('SIGINT', forwardSigint);
+    signalEmitter.on('SIGTERM', forwardSigterm);
+
+    try {
+        return await child.exited;
+    } finally {
+        signalEmitter.off('SIGINT', forwardSigint);
+        signalEmitter.off('SIGTERM', forwardSigterm);
+    }
+};
+
 export const runSpirachaDevServer = async (): Promise<number> => {
     const command = buildSpirachaDevServerCommand();
     const proc = Bun.spawn([process.execPath, ...command.args], {
@@ -24,7 +51,7 @@ export const runSpirachaDevServer = async (): Promise<number> => {
         stdout: 'inherit',
     });
 
-    return proc.exited;
+    return waitForSpirachaDevServer(proc);
 };
 
 if (import.meta.main) {

package/package.json

@@ -11,37 +11,46 @@
     },
     "dependencies": {
         "@tailwindcss/typography": "0.5.20",
-        "@tailwindcss/vite": "4.3.1",
-        "@tanstack/devtools-vite": "0.7.0",
+        "@tailwindcss/vite": "4.3.3",
+        "@tanstack/devtools-vite": "0.8.1",
         "@tanstack/match-sorter-utils": "8.19.4",
-        "@tanstack/react-devtools": "0.10.5",
-        "@tanstack/react-query": "5.101.0",
-        "@tanstack/react-query-devtools": "5.101.0",
-        "@tanstack/react-router": "1.170.15",
+        "@tanstack/react-devtools": "0.10.8",
+        "@tanstack/react-query": "5.101.2",
+        "@tanstack/react-query-devtools": "5.101.2",
+        "@tanstack/react-router": "1.170.18",
         "@tanstack/react-router-devtools": "1.167.0",
         "@tanstack/react-router-ssr-query": "1.167.1",
-        "@tanstack/react-start": "1.168.25",
+        "@tanstack/react-start": "1.168.30",
         "@tanstack/react-table": "8.21.3",
-        "@tanstack/react-virtual": "3.14.2",
-        "@tanstack/router-plugin": "1.168.18",
-        "@vitejs/plugin-react": "6.0.2",
+        "@tanstack/react-virtual": "3.14.6",
+        "@tanstack/router-plugin": "1.168.22",
+        "@vitejs/plugin-react": "6.0.3",
         "class-variance-authority": "0.7.1",
         "clsx": "2.1.1",
-        "lucide-react": "1.18.0",
-        "radix-ui": "1.5.0",
+        "fflate": "0.8.3",
+        "lucide-react": "1.25.0",
+        "radix-ui": "1.6.2",
         "react": "19.2.7",
         "react-dom": "19.2.7",
         "tailwind-merge": "3.6.0",
-        "tailwindcss": "4.3.1",
+        "tailwindcss": "4.3.3",
         "tw-animate-css": "1.4.0",
-        "vite": "8.0.16",
+        "vite": "8.1.5",
         "zod": "4.4.3"
     },
-    "description": "Browse and expose local Codex, Claude Code, Kiro, Qoder, Cursor, Antigravity, and OpenCode conversation history through a local UI and stable data API.",
+    "description": "Browse and expose local Codex, Claude Code, Grok, Kiro, Qoder, Cursor, Antigravity, and OpenCode conversation history through a local UI and stable data API.",
     "devDependencies": {
+        "@biomejs/biome": "2.5.4",
+        "@testing-library/dom": "10.4.1",
+        "@testing-library/react": "16.3.2",
         "@types/bun": "^1.3.14",
-        "@types/node": "^25.9.3",
-        "typescript": "^6.0.3"
+        "@types/node": "^26.1.1",
+        "@types/react": "19.2.17",
+        "@types/react-dom": "19.2.3",
+        "@vitest/coverage-v8": "4.1.10",
+        "jsdom": "29.1.1",
+        "typescript": "^7.0.2",
+        "vitest": "4.1.10"
     },
     "engines": {
         "bun": ">=1.3.14"
@@ -63,7 +72,6 @@
     "files": [
         "bin/spiracha.ts",
         "apps/ui/components.json",
-        "apps/ui/package.json",
         "apps/ui/public/**/*",
         "apps/ui/src/**/*",
         "!apps/ui/src/**/*.vitest.ts",
@@ -78,9 +86,13 @@
         "AGENTS.md"
     ],
     "homepage": "https://github.com/ragaeeb/spiracha",
+    "imports": {
+        "#/*": "./apps/ui/src/*"
+    },
     "keywords": [
         "codex",
         "claude",
+        "grok",
         "kiro",
         "qoder",
         "cursor",
@@ -99,21 +111,19 @@
         "url": "git+https://github.com/ragaeeb/spiracha.git"
     },
     "scripts": {
-        "build": "bun run typecheck && bun run --cwd apps/ui build",
+        "build": "bun run typecheck && bun --cwd apps/ui --bun vite build",
         "coverage": "bun run coverage:root && bun run coverage:ui",
         "coverage:root": "bun test --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run ./src/coverage-check.ts root",
-        "coverage:ui": "bun run --cwd apps/ui coverage && bun run ./src/coverage-check.ts ui",
+        "coverage:ui": "vitest run --coverage --config apps/ui/vitest.config.ts && bun run ./src/coverage-check.ts ui",
         "format": "biome check . --write && biome lint . --write",
         "lint": "biome check .",
-        "start": "bun run --cwd apps/ui dev",
+        "start": "bun --cwd apps/ui --bun vite dev --host 127.0.0.1 --port 3000",
+        "test:ui": "vitest run --config apps/ui/vitest.config.ts",
         "typecheck": "bun run typecheck:root && bun run typecheck:ui",
         "typecheck:root": "bunx tsc --noEmit",
-        "typecheck:ui": "bun run --cwd apps/ui typecheck",
-        "ui:preview": "bun run --cwd apps/ui preview"
+        "typecheck:ui": "bunx tsc --noEmit -p apps/ui/tsconfig.json",
+        "ui:preview": "bun --cwd apps/ui --bun vite preview"
     },
     "type": "module",
-    "version": "2.0.0",
-    "workspaces": [
-        "apps/*"
-    ]
+    "version": "2.2.0"
 }

package/src/client.ts

@@ -1,4 +1,7 @@
+import { mapWithConcurrency } from './lib/concurrency';
 import {
+    deleteConversation as deleteLocalConversation,
+    deleteConversations as deleteLocalConversations,
     getConversation as getLocalConversation,
     listConversationSources as listLocalConversationSources,
     listConversationsForPath as listLocalConversationsForPath,
@@ -11,10 +14,17 @@ import type {
     ConversationMessageSelector,
     ConversationPage,
     ConversationSourceInfo,
+    ConversationZipDownload,
+    DeleteConversationOptions,
+    DeleteConversationResult,
+    DeleteConversationsOptions,
+    DeleteConversationsResult,
+    ExportConversationsZipOptions,
     GetConversationOptions,
     ListConversationsForPathOptions,
     ResolvedConversationRef,
 } from './lib/conversation-data/types';
+import { createConversationMarkdownZip } from './lib/conversation-zip-export';
 
 export type {
     ConversationDataLocations,
@@ -28,6 +38,12 @@ export type {
     ConversationPathMatch,
     ConversationSource,
     ConversationSourceInfo,
+    ConversationZipDownload,
+    DeleteConversationOptions,
+    DeleteConversationResult,
+    DeleteConversationsOptions,
+    DeleteConversationsResult,
+    ExportConversationsZipOptions,
     GetConversationOptions,
     ListConversationsForPathOptions,
     ResolvedConversationRef,
@@ -36,9 +52,11 @@ export type {
 type HttpEnvelope<T> = {
     data?: T;
     error?: {
+        code?: string | null;
         message?: string | null;
     } | null;
     meta?: {
+        has_next?: boolean | null;
         hasNext?: boolean | null;
         nextCursor?: string | null;
         next_cursor?: string | null;
@@ -70,7 +88,10 @@ export type CreateConversationClientOptions = HttpConversationClientOptions | Lo
 export type ExportConversationMarkdownOptions = GetConversationOptions;
 
 export type ConversationClient = {
+    deleteConversation: (options: DeleteConversationOptions) => Promise<DeleteConversationResult | null>;
+    deleteConversations: (options: DeleteConversationsOptions) => Promise<DeleteConversationsResult | null>;
     exportConversationMarkdown: (options: ExportConversationMarkdownOptions) => Promise<string | null>;
+    exportConversationsZip: (options: ExportConversationsZipOptions) => Promise<ConversationZipDownload | null>;
     getConversation: (options: GetConversationOptions) => Promise<ConversationDetail | null>;
     listConversations: (options: ListConversationsForPathOptions) => Promise<ConversationPage>;
     listSources: () => Promise<ConversationSourceInfo[]>;
@@ -178,19 +199,53 @@ const fetchJson = async <T>(url: URL, init?: RequestInit): Promise<HttpEnvelope<
     return readJsonEnvelope(response);
 };
 
+const isMissingConversationResponse = async (response: Response): Promise<boolean> => {
+    if (response.status !== 404) {
+        return false;
+    }
+
+    try {
+        const envelope = (await response.clone().json()) as HttpEnvelope<unknown>;
+        return envelope.error?.code === 'conversation_not_found';
+    } catch {
+        return false;
+    }
+};
+
 const fetchJsonOrNull = async <T>(url: URL, init?: RequestInit): Promise<HttpEnvelope<T> | null> => {
     const response = await fetchResponse(url, init);
-    if (response.status === 404) {
+    if (await isMissingConversationResponse(response)) {
+        return null;
+    }
+
+    await assertOkResponse(response);
+    return readJsonEnvelope(response);
+};
+
+const fetchDeleteJsonOrNull = async <T>(url: URL, init?: RequestInit): Promise<HttpEnvelope<T> | null> => {
+    const response = await fetchResponse(url, init);
+    if (await isMissingConversationResponse(response)) {
         return null;
     }
 
+    if (response.status === 405) {
+        try {
+            const envelope = (await response.clone().json()) as HttpEnvelope<T>;
+            if (envelope.error?.code === 'unsupported_operation') {
+                return null;
+            }
+        } catch {
+            // Let the normal error path report malformed error responses.
+        }
+    }
+
     await assertOkResponse(response);
     return readJsonEnvelope(response);
 };
 
 const fetchTextOrNull = async (url: URL, init?: RequestInit): Promise<string | null> => {
     const response = await fetchResponse(url, init);
-    if (response.status === 404) {
+    if (await isMissingConversationResponse(response)) {
         return null;
     }
 
@@ -198,6 +253,34 @@ const fetchTextOrNull = async (url: URL, init?: RequestInit): Promise<string | n
     return response.text();
 };
 
+const fileNameFromContentDisposition = (contentDisposition: string | null, fallback: string) => {
+    const encodedMatch = contentDisposition?.match(/filename\*=UTF-8''([^;]+)/iu);
+    if (encodedMatch?.[1]) {
+        try {
+            return decodeURIComponent(encodedMatch[1]);
+        } catch {
+            return fallback;
+        }
+    }
+
+    const quotedMatch = contentDisposition?.match(/filename="([^"]+)"/iu);
+    return quotedMatch?.[1] || fallback;
+};
+
+const fetchZipOrNull = async (url: URL, init?: RequestInit): Promise<ConversationZipDownload | null> => {
+    const response = await fetchResponse(url, init);
+    if (await isMissingConversationResponse(response)) {
+        return null;
+    }
+
+    await assertOkResponse(response);
+    return {
+        blob: await response.blob(),
+        fileName: fileNameFromContentDisposition(response.headers.get('Content-Disposition'), 'conversations.zip'),
+        mimeType: 'application/zip',
+    };
+};
+
 const requireData = <T>(envelope: HttpEnvelope<T>, label: string): T => {
     if (envelope.data === undefined) {
         throw new SpirachaClientError(`Spiracha API response did not include ${label}.`);
@@ -215,13 +298,20 @@ const normalizePage = (envelope: HttpEnvelope<ConversationDetail[]>): Conversati
     return {
         data,
         meta: {
-            hasNext: envelope.meta?.hasNext === true,
+            hasNext: envelope.meta?.has_next === true || envelope.meta?.hasNext === true,
             nextCursor: envelope.meta?.nextCursor ?? envelope.meta?.next_cursor ?? null,
         },
     };
 };
 
-const makeHttpUrl = (baseUrl: URL, pathname: string): URL => new URL(pathname, baseUrl);
+const makeHttpUrl = (baseUrl: URL, pathname: string): URL => {
+    const url = new URL(baseUrl);
+    const basePath = url.pathname.replace(/\/+$/u, '');
+    url.pathname = `${basePath}/${pathname.replace(/^\/+/, '')}`;
+    url.search = '';
+    url.hash = '';
+    return url;
+};
 
 const rejectHttpLocations = (locations: ConversationDataLocations | undefined): void => {
     if (locations) {
@@ -229,11 +319,63 @@ const rejectHttpLocations = (locations: ConversationDataLocations | undefined):
     }
 };
 
+const buildBatchBody = ({ ids, messageSelector, outputFormat, source }: ExportConversationsZipOptions) => ({
+    ids,
+    message_selector: messageSelector,
+    output_format: outputFormat,
+    source,
+});
+
+const exportLocalConversationsZip = async (
+    exportOptions: ExportConversationsZipOptions,
+    locations: ConversationDataLocations | undefined,
+) => {
+    const options = withDefaultLocations(exportOptions, locations);
+    if (options.ids.length > 200) {
+        throw new SpirachaClientError('At most 200 conversation ids may be exported at once.');
+    }
+    const conversations = await mapWithConcurrency(options.ids, 4, (id) =>
+        getLocalConversation({
+            id,
+            locations: options.locations,
+            messageSelector: options.messageSelector ?? 'all',
+            source: options.source,
+        }),
+    );
+
+    if (conversations.some((conversation) => conversation === null)) {
+        return null;
+    }
+
+    return createConversationMarkdownZip({
+        entries: conversations.map((conversation, index) => {
+            const resolvedConversation = conversation!;
+            return {
+                fallbackBaseName: `${options.source}-${options.ids[index]}`,
+                markdown: renderLocalConversationMarkdown(resolvedConversation, {
+                    messageSelector: options.messageSelector ?? 'all',
+                }),
+                title: resolvedConversation.title,
+            };
+        }),
+        fileBaseName: `${options.source}-conversations-${options.ids.length}`,
+    });
+};
+
 const makeLocalClient = (options: LocalConversationClientOptions): ConversationClient => ({
+    deleteConversation: (deleteOptions) =>
+        deleteLocalConversation(withDefaultLocations(deleteOptions, options.locations)),
+    deleteConversations: (deleteOptions) =>
+        deleteLocalConversations(withDefaultLocations(deleteOptions, options.locations)),
     exportConversationMarkdown: async (getOptions) => {
         const conversation = await getLocalConversation(withDefaultLocations(getOptions, options.locations));
-        return conversation ? renderLocalConversationMarkdown(conversation) : null;
+        return conversation
+            ? renderLocalConversationMarkdown(conversation, {
+                  messageSelector: getOptions.messageSelector,
+              })
+            : null;
     },
+    exportConversationsZip: (exportOptions) => exportLocalConversationsZip(exportOptions, options.locations),
     getConversation: (getOptions) => getLocalConversation(withDefaultLocations(getOptions, options.locations)),
     listConversations: (listOptions) =>
         listLocalConversationsForPath(withDefaultLocations(listOptions, options.locations)),
@@ -245,6 +387,34 @@ const makeHttpClient = (options: HttpConversationClientOptions): ConversationCli
     const baseUrl = normalizeBaseUrl(options.baseUrl);
 
     return {
+        deleteConversation: async (deleteOptions) => {
+            rejectHttpLocations(deleteOptions.locations);
+            const { id, source } = deleteOptions;
+            const url = makeHttpUrl(baseUrl, `/api/v1/conversations/${source}/${encodeURIComponent(id)}`);
+            const envelope = await fetchDeleteJsonOrNull<DeleteConversationResult>(url, { method: 'DELETE' });
+            if (!envelope) {
+                return null;
+            }
+            return requireData(envelope, 'a delete result');
+        },
+        deleteConversations: async (deleteOptions) => {
+            rejectHttpLocations(deleteOptions.locations);
+            const envelope = await fetchDeleteJsonOrNull<DeleteConversationsResult>(
+                makeHttpUrl(baseUrl, '/api/v1/conversations/delete'),
+                {
+                    body: JSON.stringify({
+                        ids: deleteOptions.ids,
+                        source: deleteOptions.source,
+                    }),
+                    headers: { 'Content-Type': 'application/json' },
+                    method: 'POST',
+                },
+            );
+            if (!envelope) {
+                return null;
+            }
+            return requireData(envelope, 'a delete result');
+        },
         exportConversationMarkdown: async (getOptions) => {
             rejectHttpLocations(getOptions.locations);
             const { id, messageSelector, source } = getOptions;
@@ -252,6 +422,14 @@ const makeHttpClient = (options: HttpConversationClientOptions): ConversationCli
             appendMessageSelector(url, messageSelector);
             return fetchTextOrNull(url);
         },
+        exportConversationsZip: async (exportOptions) => {
+            rejectHttpLocations(exportOptions.locations);
+            return fetchZipOrNull(makeHttpUrl(baseUrl, '/api/v1/conversations/export'), {
+                body: JSON.stringify(buildBatchBody(exportOptions)),
+                headers: { 'Content-Type': 'application/json' },
+                method: 'POST',
+            });
+        },
         getConversation: async (getOptions) => {
             rejectHttpLocations(getOptions.locations);
             const { id, messageSelector, source } = getOptions;