spiracha 1.0.0 → 1.1.0

package/src/lib/path-transforms.ts

@@ -0,0 +1,45 @@
+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(/\/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,9 @@
-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';
 
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 
@@ -59,6 +60,31 @@ export const cleanExtractedText = (text: string): string => {
     return text.replace(/^\s*<\/?image>\s*$/gm, '').replace(/\n{3,}/g, '\n\n');
 };
 
+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(' ');
+};
+
 export const asObject = (value: JsonValue): Record<string, JsonValue> | null => {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         return null;
@@ -207,6 +233,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,39 @@
+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);
+};
+
+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 (!isRetryableSqliteError(error) || attempt >= delaysMs.length) {
+                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

@@ -2,8 +2,9 @@
 
 import { runExportChatsCli } from './export-chats';
 import { runExportClaudeCli } from './export-claude';
+import { runUiCli } from './ui-cli';
 
-type SpirachaCommandKind = 'codex' | 'claude' | 'help';
+type SpirachaCommandKind = 'codex' | 'claude' | 'help' | 'ui';
 
 type SpirachaInvocation = {
     kind: SpirachaCommandKind;
@@ -21,6 +22,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 +41,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 +55,7 @@ export const getSpirachaHelpText = (): string => {
         'For command-specific help:',
         '  spiracha codex --help',
         '  spiracha claude --help',
+        '  spiracha ui --help',
     ].join('\n');
 };
 
@@ -64,6 +72,11 @@ export const runSpirachaCli = async (argv = process.argv.slice(2)): Promise<void
         return;
     }
 
+    if (invocation.kind === 'ui') {
+        await runUiCli(invocation.argv);
+        return;
+    }
+
     await runExportChatsCli(invocation.argv);
 };
 

package/src/ui-cli.ts

@@ -0,0 +1,310 @@
+#!/usr/bin/env bun
+
+import { access, constants } from 'node:fs/promises';
+import path from 'node:path';
+import { openUrlNatively } from './lib/native-open';
+import { CliUsageError } from './lib/shared';
+import {
+    buildUiExportContentDisposition,
+    ensureUiExportDir,
+    resolveUiExportFilePathFromRequestPath,
+} from './lib/ui-export-files';
+
+type UiCliOptions = {
+    dbPath: string | null;
+    host: string;
+    openBrowser: boolean;
+    port: number;
+};
+
+const DEFAULT_UI_HOST = '127.0.0.1';
+const DEFAULT_UI_PORT = 3000;
+const MAX_PORT_ATTEMPTS = 10;
+
+const resolveUiDistPaths = () => {
+    const distRoot = path.resolve(import.meta.dir, '..', 'apps', 'ui', 'dist');
+    return {
+        clientDir: path.join(distRoot, 'client'),
+        serverEntryPath: path.join(distRoot, 'server', 'server.js'),
+    };
+};
+
+const ensureUiBuildExists = async () => {
+    const { clientDir, serverEntryPath } = resolveUiDistPaths();
+    const serverEntry = Bun.file(serverEntryPath);
+    const clientAssetExists = await Bun.file(path.join(clientDir, 'favicon.ico')).exists();
+    const serverEntryExists = await serverEntry.exists();
+
+    if (!clientAssetExists || !serverEntryExists) {
+        throw new Error('UI build artifacts are missing. Run `bun run build` before launching `spiracha ui`.');
+    }
+
+    await ensureUiExportDir();
+};
+
+const parsePort = (value: string) => {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw new CliUsageError(`Invalid port: ${value}`);
+    }
+
+    return parsed;
+};
+
+const requireUiArgValue = (value: string | undefined, flag: string) => {
+    if (!value) {
+        throw new CliUsageError(`Missing value for ${flag}`);
+    }
+
+    return value;
+};
+
+const applyUiCliArg = (
+    argv: string[],
+    index: number,
+    state: UiCliOptions,
+): {
+    index: number;
+    state: UiCliOptions;
+} => {
+    const arg = argv[index];
+
+    if (arg === '--no-open') {
+        return {
+            index,
+            state: {
+                ...state,
+                openBrowser: false,
+            },
+        };
+    }
+
+    if (arg === '--port') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                port: parsePort(requireUiArgValue(argv[index + 1], '--port')),
+            },
+        };
+    }
+
+    if (arg === '--host') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                host: requireUiArgValue(argv[index + 1], '--host'),
+            },
+        };
+    }
+
+    if (arg === '--db') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                dbPath: requireUiArgValue(argv[index + 1], '--db'),
+            },
+        };
+    }
+
+    throw new CliUsageError(`Unknown UI argument: ${arg}`);
+};
+
+export const parseUiCliArgs = (argv: string[]): UiCliOptions => {
+    let state: UiCliOptions = {
+        dbPath: null,
+        host: DEFAULT_UI_HOST,
+        openBrowser: true,
+        port: DEFAULT_UI_PORT,
+    };
+
+    for (let index = 0; index < argv.length; index += 1) {
+        const next = applyUiCliArg(argv, index, state);
+        state = next.state;
+        index = next.index;
+    }
+
+    return state;
+};
+
+export const getUiHelpText = (): string => {
+    return [
+        'Launch the Spiracha browser UI.',
+        '',
+        'Usage:',
+        '  spiracha ui [--port 3000] [--host 127.0.0.1] [--db FILE] [--no-open]',
+        '',
+        'Options:',
+        `  --port     HTTP port to bind (default: ${DEFAULT_UI_PORT})`,
+        `  --host     Hostname to bind (default: ${DEFAULT_UI_HOST})`,
+        '  --db       Override the Codex SQLite database path for the UI',
+        '  --no-open  Do not open the browser automatically',
+        '  --help,-h  Show this help text',
+        '',
+        'Stop the UI with Ctrl+C.',
+    ].join('\n');
+};
+
+const toPublicFilePath = (clientDir: string, pathname: string) => {
+    const normalizedPath = pathname === '/' ? '' : pathname.replace(/^\/+/u, '');
+    const resolved = path.resolve(clientDir, normalizedPath);
+    const relative = path.relative(clientDir, resolved);
+
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return null;
+    }
+
+    return resolved;
+};
+
+export const getUiStaticResponse = async (clientDir: string, pathname: string): Promise<Response | null> => {
+    if (pathname === '/') {
+        return null;
+    }
+
+    const exportFilePath = resolveUiExportFilePathFromRequestPath(pathname);
+    if (exportFilePath) {
+        try {
+            await access(exportFilePath, constants.R_OK);
+        } catch {
+            return new Response('Not Found', { status: 404 });
+        }
+
+        return new Response(Bun.file(exportFilePath), {
+            headers: {
+                'cache-control': 'no-store',
+                'content-disposition': buildUiExportContentDisposition(exportFilePath),
+            },
+        });
+    }
+
+    const targetPath = toPublicFilePath(clientDir, pathname);
+    if (!targetPath) {
+        return new Response('Forbidden', { status: 403 });
+    }
+
+    const file = Bun.file(targetPath);
+    if (!(await file.exists())) {
+        return null;
+    }
+
+    return new Response(file);
+};
+
+const openBrowserIfRequested = async (url: string, openBrowser: boolean) => {
+    if (!openBrowser) {
+        return;
+    }
+
+    try {
+        await openUrlNatively(url);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Could not open the browser automatically: ${message}`);
+    }
+};
+
+const startUiServer = async (options: UiCliOptions) => {
+    await ensureUiBuildExists();
+    const { clientDir, serverEntryPath } = resolveUiDistPaths();
+    const serverModule = (await import(serverEntryPath)) as {
+        default: {
+            fetch: (request: Request) => Promise<Response> | Response;
+        };
+    };
+
+    if (options.dbPath) {
+        process.env.SPIRACHA_CODEX_DB = options.dbPath;
+    }
+
+    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt += 1) {
+        const port = options.port + attempt;
+
+        try {
+            const server = Bun.serve({
+                fetch: async (request) => {
+                    const url = new URL(request.url);
+                    const staticResponse = await getUiStaticResponse(clientDir, url.pathname);
+                    if (staticResponse) {
+                        return staticResponse;
+                    }
+
+                    return serverModule.default.fetch(request);
+                },
+                hostname: options.host,
+                idleTimeout: 30,
+                port,
+            });
+
+            return {
+                port,
+                server,
+            };
+        } catch (error) {
+            if (
+                attempt < MAX_PORT_ATTEMPTS - 1 &&
+                error instanceof Error &&
+                /address already in use|EADDRINUSE/i.test(error.message)
+            ) {
+                continue;
+            }
+
+            throw error;
+        }
+    }
+
+    throw new Error(`Unable to bind the UI server after ${MAX_PORT_ATTEMPTS} port attempts.`);
+};
+
+export const runUiCli = async (argv = process.argv.slice(2)) => {
+    try {
+        if (argv.includes('--help') || argv.includes('-h')) {
+            console.log(getUiHelpText());
+            return;
+        }
+        const options = parseUiCliArgs(argv);
+        const { port, server } = await startUiServer(options);
+        const url = `http://${options.host}:${port}`;
+
+        console.log(`Spiracha UI running at ${url}`);
+        console.log('Press Ctrl+C to stop.');
+
+        await openBrowserIfRequested(url, options.openBrowser);
+
+        let shuttingDown = false;
+        const shutdown = () => {
+            if (shuttingDown) {
+                return;
+            }
+            shuttingDown = true;
+            server.stop(true);
+            console.log('Spiracha UI stopped.');
+            process.exit(0);
+        };
+
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+
+        await new Promise<void>(() => {});
+    } catch (error) {
+        if (error instanceof CliUsageError) {
+            console.error(error.message);
+            console.error('');
+            console.error(getUiHelpText());
+            process.exit(1);
+        }
+
+        if (error instanceof Error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+
+        throw error;
+    }
+};
+
+if (import.meta.main) {
+    await runUiCli();
+}