spiracha 1.0.0

package/src/lib/shared.ts

@@ -0,0 +1,224 @@
+import { createReadStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+export type ExportFormat = 'md' | 'txt';
+
+export type MetadataEntry = {
+    key: string;
+    value: unknown;
+};
+
+export class CliUsageError extends Error {}
+
+export const expandHome = (value: string): string => {
+    if (!value) {
+        return value;
+    }
+
+    if (value === '~') {
+        return os.homedir();
+    }
+
+    if (value.startsWith('~/')) {
+        return path.join(os.homedir(), value.slice(2));
+    }
+
+    return value;
+};
+
+export const getPortablePathBasename = (value: string): string => {
+    const trimmed = value.replace(/[\\/]+$/u, '');
+    if (!trimmed) {
+        return '';
+    }
+
+    return path.win32.basename(path.posix.basename(trimmed));
+};
+
+export const cleanInlineTitle = (value: string): string => {
+    const firstLine =
+        value
+            .split('\n')
+            .map((line) => line.trim())
+            .find((line) => line.length > 0) ?? '';
+    const compact = firstLine.replace(/\s+/g, ' ').trim();
+
+    if (compact.length <= 160) {
+        return compact;
+    }
+
+    return `${compact.slice(0, 157).trimEnd()}...`;
+};
+
+export const cleanExtractedText = (text: string): string => {
+    return text.replace(/^\s*<\/?image>\s*$/gm, '').replace(/\n{3,}/g, '\n\n');
+};
+
+export const asObject = (value: JsonValue): Record<string, JsonValue> | null => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+
+    return value as Record<string, JsonValue>;
+};
+
+export const asString = (value: JsonValue): string | null => {
+    return typeof value === 'string' ? value : null;
+};
+
+export const asNumber = (value: JsonValue): number | null => {
+    return typeof value === 'number' ? value : null;
+};
+
+export const asBoolean = (value: JsonValue): boolean => {
+    return value === true;
+};
+
+export const readJsonlObjects = (filePath: string): AsyncIterableIterator<Record<string, JsonValue>> => {
+    const stream = createReadStream(filePath, { encoding: 'utf8' });
+    const lines = createInterface({
+        crlfDelay: Infinity,
+        input: stream,
+    });
+    const lineIterator = lines[Symbol.asyncIterator]();
+    let closed = false;
+
+    const close = () => {
+        if (closed) {
+            return;
+        }
+
+        closed = true;
+        lines.close();
+        stream.destroy();
+    };
+
+    const readNext = async (): Promise<IteratorResult<Record<string, JsonValue>>> => {
+        while (true) {
+            const nextLine = await lineIterator.next();
+            if (nextLine.done) {
+                close();
+                return { done: true, value: undefined as never };
+            }
+
+            const trimmed = nextLine.value.trim();
+            if (!trimmed) {
+                continue;
+            }
+
+            try {
+                return {
+                    done: false,
+                    value: JSON.parse(trimmed) as Record<string, JsonValue>,
+                };
+            } catch {}
+        }
+    };
+
+    const iterator: AsyncIterableIterator<Record<string, JsonValue>> = {
+        [Symbol.asyncIterator]: () => iterator,
+        next: async () => readNext(),
+        return: async () => {
+            close();
+            return { done: true, value: undefined as never };
+        },
+        throw: async (error?: unknown) => {
+            close();
+            throw error;
+        },
+    };
+
+    return iterator;
+};
+
+export const renderDocumentTitle = (title: string, format: ExportFormat): string => {
+    if (format === 'md') {
+        return `# ${title}`;
+    }
+
+    return [title, '='.repeat(Math.max(title.length, 3))].join('\n');
+};
+
+export const renderMetadataBlock = (entries: MetadataEntry[], format: ExportFormat): string => {
+    const filteredEntries = entries.filter(
+        (entry) => entry.value !== null && entry.value !== undefined && entry.value !== '',
+    );
+
+    if (filteredEntries.length === 0) {
+        return '';
+    }
+
+    if (format === 'md') {
+        const lines = ['---'];
+        for (const entry of filteredEntries) {
+            lines.push(`${entry.key}: ${toMetadataValue(entry.value, 'md')}`);
+        }
+        lines.push('---');
+        return `${lines.join('\n')}\n`;
+    }
+
+    const lines = ['Metadata', '--------'];
+    for (const entry of filteredEntries) {
+        lines.push(`${entry.key}: ${toMetadataValue(entry.value, 'txt')}`);
+    }
+    return `${lines.join('\n')}\n`;
+};
+
+export const renderSection = (title: string, body: string, format: ExportFormat): string => {
+    const trimmedBody = body.trimEnd();
+    if (!trimmedBody) {
+        return '';
+    }
+
+    if (format === 'md') {
+        return `## ${title}\n\n${trimmedBody}\n`;
+    }
+
+    return `${title}\n${'-'.repeat(Math.max(title.length, 3))}\n${trimmedBody}\n`;
+};
+
+export const renderCodeBlock = (text: string, format: ExportFormat): string => {
+    if (format === 'md') {
+        return `\`\`\`text\n${text}\n\`\`\``;
+    }
+
+    return text;
+};
+
+export const formatInlineLiteral = (value: string, format: ExportFormat): string => {
+    return format === 'md' ? inlineCode(value) : value;
+};
+
+export const inlineCode = (value: string): string => {
+    const backtickRuns = value.match(/`+/g) ?? [];
+    const maxRunLength = backtickRuns.reduce((max, run) => Math.max(max, run.length), 0);
+    const fence = '`'.repeat(maxRunLength + 1);
+    const padded = value.startsWith('`') || value.endsWith('`') ? ` ${value} ` : value;
+    return `${fence}${padded}${fence}`;
+};
+
+export const writeExportFile = async (outputPath: string, content: string) => {
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await Bun.write(outputPath, content);
+};
+
+const toMetadataValue = (value: unknown, format: ExportFormat): string => {
+    if (Array.isArray(value) || (value && typeof value === 'object')) {
+        return JSON.stringify(value);
+    }
+
+    if (typeof value === 'string') {
+        return format === 'md' ? JSON.stringify(value) : value;
+    }
+
+    if (typeof value === 'boolean' || typeof value === 'number') {
+        return String(value);
+    }
+
+    return format === 'md' ? JSON.stringify(String(value)) : String(value);
+};

package/src/mcp-server.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { AnySchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { z } from 'zod';
+import { runClaudeExport } from './lib/claude-exporter';
+import {
+    DEFAULT_DB_PATH,
+    DEFAULT_INPUT_DIR,
+    parseThreadSelectionArg,
+    resolveDefaultOutputDir,
+    runCodexExport,
+} from './lib/codex-exporter';
+import { expandHome } from './lib/shared';
+
+const server = new McpServer({
+    name: 'codex-chats-export',
+    version: '0.1.0',
+});
+
+const exportCodexChatsInputSchema = {
+    cwd: z.string().optional().describe('Optional exact cwd filter'),
+    dbPath: z.string().optional().describe('Optional override for the Codex SQLite database'),
+    deeplinks: z.array(z.string()).optional().describe('Optional Codex deeplinks like codex://threads/<thread-id>'),
+    flat: z.boolean().optional().describe('Write output into a single flat folder'),
+    includeTools: z.boolean().optional().describe('Include exec_command tool logs'),
+    inputDir: z.string().optional().describe('Optional override for the Codex sessions directory'),
+    optimized: z.boolean().optional().describe('Suppress metadata and optimize for compact text'),
+    outputDir: z.string().optional().describe('Optional output directory'),
+    outputFormat: z.enum(['md', 'txt']).optional().describe('Output format'),
+    project: z.string().optional().describe('Optional project name matched against path basename'),
+} as unknown as Record<string, AnySchema>;
+
+const exportClaudeTranscriptInputSchema = {
+    includeTools: z.boolean().optional().describe('Include Bash tool calls and outputs'),
+    inputPath: z.string().describe('Path to a Claude transcript .jsonl file or export directory'),
+    outputFormat: z.enum(['md', 'txt']).optional().describe('Output format'),
+    outputPath: z.string().optional().describe('Optional output file path or directory'),
+} as unknown as Record<string, AnySchema>;
+
+server.registerTool(
+    'export_codex_chats',
+    {
+        description: 'Export Codex chats by deeplink, project name, or cwd to markdown or plain text.',
+        inputSchema: exportCodexChatsInputSchema,
+    },
+    async (args: any) => {
+        const threadIds = parseThreadSelections(args.deeplinks ?? []);
+        const cwdFilter = args.cwd ? expandHome(args.cwd) : null;
+
+        if (threadIds.length === 0 && !args.project && !cwdFilter) {
+            throw new Error(
+                'Provide at least one deeplink, project, or cwd filter to avoid exporting the entire Codex history by accident.',
+            );
+        }
+
+        const result = await runCodexExport({
+            cwdFilter,
+            dbPath: expandHome(args.dbPath ?? DEFAULT_DB_PATH),
+            flat: args.flat ?? false,
+            includeTools: args.includeTools ?? false,
+            inputDir: expandHome(args.inputDir ?? DEFAULT_INPUT_DIR),
+            optimized: args.optimized ?? false,
+            outputDir: args.outputDir ? expandHome(args.outputDir) : resolveDefaultOutputDir(cwdFilter),
+            outputFormat: args.outputFormat ?? 'md',
+            projectFilter: args.project ?? null,
+            threadIds,
+        });
+
+        return {
+            content: [
+                {
+                    text: JSON.stringify(
+                        {
+                            exportedCount: result.exportedCount,
+                            files: result.files,
+                            missingThreadIds: result.missingThreadIds,
+                            outputDir: result.outputDir,
+                        },
+                        null,
+                        2,
+                    ),
+                    type: 'text',
+                },
+            ],
+        };
+    },
+);
+
+server.registerTool(
+    'export_claude_transcript',
+    {
+        description: 'Export a Claude Code transcript JSONL or export directory to markdown or plain text.',
+        inputSchema: exportClaudeTranscriptInputSchema,
+    },
+    async (args: any) => {
+        const result = await runClaudeExport({
+            includeTools: args.includeTools ?? false,
+            inputPath: expandHome(args.inputPath),
+            outputFormat: args.outputFormat ?? 'md',
+            outputPath: args.outputPath ? expandHome(args.outputPath) : null,
+        });
+
+        return {
+            content: [
+                {
+                    text: JSON.stringify(result, null, 2),
+                    type: 'text',
+                },
+            ],
+        };
+    },
+);
+
+const main = async () => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+};
+
+const parseThreadSelections = (deeplinks: string[]): string[] => {
+    return deeplinks.map((deeplink) => {
+        const threadId = parseThreadSelectionArg(deeplink);
+        if (!threadId) {
+            throw new Error(`Invalid Codex deeplink: ${deeplink}. Expected codex://threads/<thread-id>`);
+        }
+
+        return threadId;
+    });
+};
+
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/src/spiracha.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+
+import { runExportChatsCli } from './export-chats';
+import { runExportClaudeCli } from './export-claude';
+
+type SpirachaCommandKind = 'codex' | 'claude' | 'help';
+
+type SpirachaInvocation = {
+    kind: SpirachaCommandKind;
+    argv: string[];
+};
+
+export const resolveSpirachaInvocation = (argv: string[]): SpirachaInvocation => {
+    const [firstArg, ...rest] = argv;
+
+    if (firstArg === 'claude') {
+        return { argv: rest, kind: 'claude' };
+    }
+
+    if (firstArg === 'codex') {
+        return { argv: rest, kind: 'codex' };
+    }
+
+    if (firstArg === '--help' || firstArg === '-h' || firstArg === 'help') {
+        return { argv: [], kind: 'help' };
+    }
+
+    return { argv, kind: 'codex' };
+};
+
+export const getSpirachaHelpText = (): string => {
+    return [
+        'spiracha - export Codex chats and Claude transcripts',
+        '',
+        'Usage:',
+        '  spiracha',
+        '  spiracha codex [Codex options]',
+        '  spiracha claude [Claude options]',
+        '',
+        'Commands:',
+        '  codex   Export Codex chats (default when no subcommand is provided)',
+        '  claude  Export a Claude transcript file or export directory',
+        '',
+        'Aliases:',
+        '  codex-chats',
+        '  codex-chats-claude',
+        '',
+        'For command-specific help:',
+        '  spiracha codex --help',
+        '  spiracha claude --help',
+    ].join('\n');
+};
+
+export const runSpirachaCli = async (argv = process.argv.slice(2)): Promise<void> => {
+    const invocation = resolveSpirachaInvocation(argv);
+
+    if (invocation.kind === 'help') {
+        console.log(getSpirachaHelpText());
+        return;
+    }
+
+    if (invocation.kind === 'claude') {
+        await runExportClaudeCli(invocation.argv);
+        return;
+    }
+
+    await runExportChatsCli(invocation.argv);
+};
+
+if (import.meta.main) {
+    await runSpirachaCli();
+}