spiracha 1.0.0 → 1.1.1

package/src/lib/model-label.ts

@@ -0,0 +1,24 @@
+export const formatModelLabel = (value: string | null | undefined): string => {
+    if (!value) {
+        return 'Assistant';
+    }
+
+    return value
+        .split(/[-_\s]+/u)
+        .filter(Boolean)
+        .map((part) => {
+            const lower = part.toLowerCase();
+            if (lower === 'gpt') {
+                return 'GPT';
+            }
+            if (/^[a-z]\d$/u.test(lower)) {
+                return lower.toUpperCase();
+            }
+            if (/^\d+(\.\d+)*$/u.test(part)) {
+                return part;
+            }
+
+            return `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`;
+        })
+        .join(' ');
+};

package/src/lib/native-open.ts

@@ -0,0 +1,54 @@
+type NativeOpenTarget = {
+    kind: 'path' | 'url';
+    value: string;
+};
+
+const resolveNativeOpenCommand = () => {
+    if (process.platform === 'darwin') {
+        return {
+            argv: (target: NativeOpenTarget) => ['open', target.value],
+            label: 'open',
+        };
+    }
+
+    if (process.platform === 'win32') {
+        return {
+            argv: (target: NativeOpenTarget) => ['cmd', '/c', 'start', '', target.value],
+            label: 'start',
+        };
+    }
+
+    return {
+        argv: (target: NativeOpenTarget) => ['xdg-open', target.value],
+        label: 'xdg-open',
+    };
+};
+
+const openNatively = async (target: NativeOpenTarget) => {
+    const command = resolveNativeOpenCommand();
+    const proc = Bun.spawn(command.argv(target), {
+        stderr: 'pipe',
+        stdout: 'ignore',
+    });
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) {
+        const errorText = await new Response(proc.stderr).text();
+        throw new Error(
+            `Failed to open ${target.value} with ${command.label}: ${errorText.trim() || `exit code ${exitCode}`}`,
+        );
+    }
+};
+
+export const openPathNatively = async (targetPath: string) => {
+    await openNatively({
+        kind: 'path',
+        value: targetPath,
+    });
+};
+
+export const openUrlNatively = async (url: string) => {
+    await openNatively({
+        kind: 'url',
+        value: url,
+    });
+};

package/src/lib/path-transforms.ts

@@ -0,0 +1,46 @@
+export type PathDisplaySettings = {
+    convertToProjectRoot: boolean;
+    projectPath?: string | null;
+    redactUsername: boolean;
+};
+
+const escapeForRegex = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+
+const toUniquePathVariants = (projectPath: string) => {
+    const normalized = projectPath.trim();
+    const variants = [normalized, normalized.replaceAll('\\', '/'), normalized.replaceAll('/', '\\')].filter(Boolean);
+    return [...new Set(variants)].sort((left, right) => right.length - left.length);
+};
+
+const replaceExactProjectPath = (text: string, projectPath: string) => {
+    let result = text;
+
+    for (const variant of toUniquePathVariants(projectPath)) {
+        const escapedVariant = escapeForRegex(variant);
+        result = result.replace(new RegExp(`${escapedVariant}(?<separator>[\\\\/])`, 'gu'), '');
+        result = result.replace(new RegExp(`${escapedVariant}(?=$|[^A-Za-z0-9._-])`, 'gu'), '.');
+    }
+
+    return result;
+};
+
+const redactRemainingUsernames = (text: string) => {
+    return text
+        .replace(/\/home\/[^/\\]+(?=\/|$)/gu, '~')
+        .replace(/\/Users\/[^/\\]+(?=\/|$)/gu, '~')
+        .replace(/[A-Za-z]:[\\/]+Users[\\/]+[^\\/]+(?=[\\/]|$)/gu, '~');
+};
+
+export const applyPathTransforms = (text: string, settings: PathDisplaySettings): string => {
+    let result = text;
+
+    if (settings.convertToProjectRoot && settings.projectPath) {
+        result = replaceExactProjectPath(result, settings.projectPath);
+    }
+
+    if (settings.redactUsername) {
+        result = redactRemainingUsernames(result);
+    }
+
+    return result;
+};

package/src/lib/shared.ts

@@ -1,8 +1,10 @@
-import { createReadStream } from 'node:fs';
+import { createReadStream, createWriteStream } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
+import { finished } from 'node:stream/promises';
+import { formatModelLabel as formatSharedModelLabel } from './model-label';
 
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 
@@ -59,6 +61,8 @@ export const cleanExtractedText = (text: string): string => {
     return text.replace(/^\s*<\/?image>\s*$/gm, '').replace(/\n{3,}/g, '\n\n');
 };
 
+export const formatModelLabel = formatSharedModelLabel;
+
 export const asObject = (value: JsonValue): Record<string, JsonValue> | null => {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         return null;
@@ -207,6 +211,16 @@ export const writeExportFile = async (outputPath: string, content: string) => {
     await Bun.write(outputPath, content);
 };
 
+export const createExportWriteStream = async (outputPath: string) => {
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    return createWriteStream(outputPath, { encoding: 'utf8' });
+};
+
+export const finalizeExportWriteStream = async (stream: NodeJS.WritableStream) => {
+    stream.end();
+    await finished(stream);
+};
+
 const toMetadataValue = (value: unknown, format: ExportFormat): string => {
     if (Array.isArray(value) || (value && typeof value === 'object')) {
         return JSON.stringify(value);

package/src/lib/sqlite-error.ts

@@ -0,0 +1,14 @@
+const SQLITE_RETRYABLE_PATTERNS = [
+    /unable to open database file/iu,
+    /database is locked/iu,
+    /SQLITE_BUSY/iu,
+    /SQLITE_CANTOPEN/iu,
+];
+
+export const isRetryableSqliteError = (error: unknown) => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+
+    return SQLITE_RETRYABLE_PATTERNS.some((pattern) => pattern.test(error.message));
+};

package/src/lib/sqlite-retry.ts

@@ -0,0 +1,53 @@
+import { isRetryableSqliteError } from './sqlite-error';
+
+const DEFAULT_RETRY_DELAYS_MS = [40, 120, 250] as const;
+const SLEEP_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+
+type SyncRetryOptions<T> = {
+    action: () => T;
+    delaysMs?: readonly number[];
+    sleep?: (delayMs: number) => void;
+};
+
+const sleepSync = (delayMs: number) => {
+    if (delayMs <= 0) {
+        return;
+    }
+
+    Atomics.wait(SLEEP_BUFFER, 0, 0, delayMs);
+};
+
+const toRetryExhaustedError = (attemptCount: number, error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(`SQLite operation failed after ${attemptCount} attempts: ${message}`, {
+        cause: error,
+    });
+};
+
+const shouldRetrySqliteError = (error: unknown, attempt: number, delaysMs: readonly number[]) => {
+    return isRetryableSqliteError(error) && attempt < delaysMs.length;
+};
+
+export const runWithSqliteRetry = <T>({
+    action,
+    delaysMs = DEFAULT_RETRY_DELAYS_MS,
+    sleep = sleepSync,
+}: SyncRetryOptions<T>): T => {
+    let attempt = 0;
+
+    while (true) {
+        try {
+            return action();
+        } catch (error) {
+            if (!shouldRetrySqliteError(error, attempt, delaysMs)) {
+                if (isRetryableSqliteError(error)) {
+                    throw toRetryExhaustedError(attempt + 1, error);
+                }
+                throw error;
+            }
+
+            sleep(delaysMs[attempt] ?? 0);
+            attempt += 1;
+        }
+    }
+};

package/src/lib/ui-cache.ts

@@ -0,0 +1,96 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const CACHE_DIR = path.join(os.tmpdir(), 'spiracha-ui-cache');
+const CACHE_ENVELOPE_VERSION = 1;
+
+type CacheEnvelope<T> = {
+    value: T;
+    version: number;
+};
+
+const ensureCacheDir = async () => {
+    await mkdir(CACHE_DIR, { recursive: true });
+};
+
+const toCachePath = (key: string) => {
+    const safeKey = key.replace(/[^a-zA-Z0-9._-]/gu, '_');
+    return path.join(CACHE_DIR, `${safeKey}-${hashCacheKeyParts(key)}.json`);
+};
+
+export const hashCacheKeyParts = (...parts: string[]) => {
+    return createHash('sha1').update(parts.join('|')).digest('hex');
+};
+
+export const getFileFingerprint = async (filePath: string) => {
+    const metadata = await stat(filePath);
+    return `${filePath}:${metadata.size}:${metadata.mtimeMs}`;
+};
+
+export const getCachedJson = async <T>(key: string): Promise<T | null> => {
+    await ensureCacheDir();
+    const filePath = toCachePath(key);
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+        return null;
+    }
+
+    let parsed: CacheEnvelope<T> | T;
+    try {
+        parsed = (await file.json()) as CacheEnvelope<T> | T;
+    } catch {
+        await rm(filePath, { force: true });
+        return null;
+    }
+
+    if (
+        parsed &&
+        typeof parsed === 'object' &&
+        'version' in parsed &&
+        (parsed as CacheEnvelope<T>).version === CACHE_ENVELOPE_VERSION &&
+        'value' in parsed
+    ) {
+        return (parsed as CacheEnvelope<T>).value;
+    }
+
+    return parsed as T;
+};
+
+export const setCachedJson = async <T>(key: string, value: T) => {
+    await ensureCacheDir();
+    const filePath = toCachePath(key);
+    const tempPath = `${filePath}.${randomUUID()}.tmp`;
+    const envelope: CacheEnvelope<T> = {
+        value,
+        version: CACHE_ENVELOPE_VERSION,
+    };
+
+    await Bun.write(tempPath, JSON.stringify(envelope));
+    await rename(tempPath, filePath);
+};
+
+export const withCachedJson = async <T>(key: string, loader: () => Promise<T>): Promise<T> => {
+    const filePath = toCachePath(key);
+    const existedBeforeRead = await Bun.file(filePath).exists();
+    const cached = await getCachedJson<T>(key);
+    if (cached !== null || (existedBeforeRead && (await Bun.file(filePath).exists()))) {
+        return cached as T;
+    }
+
+    const value = await loader();
+    await setCachedJson(key, value);
+    return value;
+};
+
+export const invalidateCacheByPrefix = async (...prefixes: string[]) => {
+    await ensureCacheDir();
+    const entries = await readdir(CACHE_DIR);
+
+    await Promise.all(
+        entries
+            .filter((entry) => prefixes.some((prefix) => entry.startsWith(prefix)))
+            .map((entry) => rm(path.join(CACHE_DIR, entry), { force: true })),
+    );
+};

package/src/lib/ui-export-files.ts

@@ -0,0 +1,77 @@
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const UI_EXPORT_DIR_ENV = 'SPIRACHA_UI_EXPORT_DIR';
+export const UI_EXPORT_URL_PREFIX = '/__exports/';
+
+const DEFAULT_UI_EXPORT_DIR = path.join(os.tmpdir(), 'spiracha-ui-exports');
+const DEFAULT_EXPORT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+const decodeExportFileName = (value: string) => {
+    try {
+        return decodeURIComponent(value);
+    } catch {
+        return null;
+    }
+};
+
+const isSafeExportFileName = (value: string) => {
+    return value.length > 0 && value === path.basename(value) && !/[\\/]/u.test(value) && !value.includes('\0');
+};
+
+export const getUiExportDir = () => {
+    return process.env[UI_EXPORT_DIR_ENV]?.trim() || DEFAULT_UI_EXPORT_DIR;
+};
+
+export const ensureUiExportDir = async () => {
+    const exportDir = getUiExportDir();
+    await mkdir(exportDir, { recursive: true });
+    await purgeStaleUiExports(exportDir);
+    return exportDir;
+};
+
+export const buildUiExportDownloadUrl = (filePath: string) => {
+    return `${UI_EXPORT_URL_PREFIX}${encodeURIComponent(path.basename(filePath))}`;
+};
+
+export const buildUiExportContentDisposition = (filePath: string) => {
+    const fileName = path.basename(filePath);
+    return `attachment; filename*=UTF-8''${encodeURIComponent(fileName)}`;
+};
+
+export const purgeStaleUiExports = async (
+    exportDir: string = getUiExportDir(),
+    maxAgeMs: number = DEFAULT_EXPORT_MAX_AGE_MS,
+) => {
+    const entries = await readdir(exportDir, { withFileTypes: true });
+    const cutoff = Date.now() - maxAgeMs;
+
+    await Promise.all(
+        entries
+            .filter((entry) => entry.isFile())
+            .map(async (entry) => {
+                const filePath = path.join(exportDir, entry.name);
+                const metadata = await stat(filePath);
+                if (metadata.mtimeMs >= cutoff) {
+                    return;
+                }
+
+                await rm(filePath, { force: true });
+            }),
+    );
+};
+
+export const resolveUiExportFilePathFromRequestPath = (pathname: string) => {
+    if (!pathname.startsWith(UI_EXPORT_URL_PREFIX)) {
+        return null;
+    }
+
+    const rawFileName = pathname.slice(UI_EXPORT_URL_PREFIX.length);
+    const fileName = decodeExportFileName(rawFileName);
+    if (!fileName || !isSafeExportFileName(fileName)) {
+        return null;
+    }
+
+    return path.join(getUiExportDir(), fileName);
+};

package/src/mcp-server.ts

@@ -59,6 +59,7 @@ server.registerTool(
             cwdFilter,
             dbPath: expandHome(args.dbPath ?? DEFAULT_DB_PATH),
             flat: args.flat ?? false,
+            includeCommentary: true,
             includeTools: args.includeTools ?? false,
             inputDir: expandHome(args.inputDir ?? DEFAULT_INPUT_DIR),
             optimized: args.optimized ?? false,

package/src/spiracha.ts

@@ -1,9 +1,6 @@
 #!/usr/bin/env bun
 
-import { runExportChatsCli } from './export-chats';
-import { runExportClaudeCli } from './export-claude';
-
-type SpirachaCommandKind = 'codex' | 'claude' | 'help';
+type SpirachaCommandKind = 'codex' | 'claude' | 'help' | 'ui';
 
 type SpirachaInvocation = {
     kind: SpirachaCommandKind;
@@ -21,6 +18,10 @@ export const resolveSpirachaInvocation = (argv: string[]): SpirachaInvocation =>
         return { argv: rest, kind: 'codex' };
     }
 
+    if (firstArg === 'ui') {
+        return { argv: rest, kind: 'ui' };
+    }
+
     if (firstArg === '--help' || firstArg === '-h' || firstArg === 'help') {
         return { argv: [], kind: 'help' };
     }
@@ -36,10 +37,12 @@ export const getSpirachaHelpText = (): string => {
         '  spiracha',
         '  spiracha codex [Codex options]',
         '  spiracha claude [Claude options]',
+        '  spiracha ui [UI options]',
         '',
         'Commands:',
         '  codex   Export Codex chats (default when no subcommand is provided)',
         '  claude  Export a Claude transcript file or export directory',
+        '  ui      Launch the local browser UI for browsing Codex history',
         '',
         'Aliases:',
         '  codex-chats',
@@ -48,6 +51,7 @@ export const getSpirachaHelpText = (): string => {
         'For command-specific help:',
         '  spiracha codex --help',
         '  spiracha claude --help',
+        '  spiracha ui --help',
     ].join('\n');
 };
 
@@ -60,10 +64,18 @@ export const runSpirachaCli = async (argv = process.argv.slice(2)): Promise<void
     }
 
     if (invocation.kind === 'claude') {
+        const { runExportClaudeCli } = await import('./export-claude');
         await runExportClaudeCli(invocation.argv);
         return;
     }
 
+    if (invocation.kind === 'ui') {
+        const { runUiCli } = await import('./ui-cli');
+        await runUiCli(invocation.argv);
+        return;
+    }
+
+    const { runExportChatsCli } = await import('./export-chats');
     await runExportChatsCli(invocation.argv);
 };