spiracha 1.0.0

package/src/lib/codex-exporter-cli.ts

@@ -0,0 +1,272 @@
+import path from 'node:path';
+import { type CodexCliOptions, DEFAULT_DB_PATH, DEFAULT_INPUT_DIR, DEFAULT_OUTPUT_DIR } from './codex-exporter-types';
+import { CliUsageError, type ExportFormat, expandHome, getPortablePathBasename } from './shared';
+
+export const parseCodexCliArgs = (argv: string[]): CodexCliOptions => {
+    let dbPath = DEFAULT_DB_PATH;
+    let inputDir = DEFAULT_INPUT_DIR;
+    let outputDir: string | null = null;
+    let cwdFilter: string | null = null;
+    let projectFilter: string | null = null;
+    let threadIds: string[] = [];
+    let outputProvided = false;
+    let optimized = false;
+    let includeTools = false;
+    let outputFormat: ExportFormat = 'md';
+    let flat = false;
+
+    for (let index = 0; index < argv.length; index += 1) {
+        const nextIndex = applyCodexCliArg(argv, index, {
+            cwdFilter,
+            dbPath,
+            flat,
+            includeTools,
+            inputDir,
+            optimized,
+            outputDir,
+            outputFormat,
+            outputProvided,
+            projectFilter,
+            threadIds,
+        });
+
+        ({
+            cwdFilter,
+            dbPath,
+            flat,
+            includeTools,
+            inputDir,
+            optimized,
+            outputDir,
+            outputFormat,
+            outputProvided,
+            projectFilter,
+            threadIds,
+        } = nextIndex.state);
+        index = nextIndex.index;
+    }
+
+    if (!outputProvided) {
+        outputDir = resolveDefaultOutputDir(cwdFilter);
+    }
+
+    return {
+        cwdFilter,
+        dbPath,
+        flat,
+        includeTools,
+        inputDir,
+        optimized,
+        outputDir: outputDir ?? DEFAULT_OUTPUT_DIR,
+        outputFormat,
+        projectFilter,
+        threadIds: [...new Set(threadIds)],
+    };
+};
+
+type CodexCliState = {
+    cwdFilter: string | null;
+    dbPath: string;
+    flat: boolean;
+    includeTools: boolean;
+    inputDir: string;
+    optimized: boolean;
+    outputDir: string | null;
+    outputFormat: ExportFormat;
+    outputProvided: boolean;
+    projectFilter: string | null;
+    threadIds: string[];
+};
+
+type CodexCliNext = {
+    index: number;
+    state: CodexCliState;
+};
+
+const applyCodexCliArg = (argv: string[], index: number, state: CodexCliState): CodexCliNext => {
+    const arg = argv[index];
+
+    if (arg === '--db') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                dbPath: expandHome(requireValue(argv[index + 1], '--db')),
+            },
+        };
+    }
+
+    if (arg === '--input' || arg === '-i') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                inputDir: expandHome(requireValue(argv[index + 1], arg)),
+            },
+        };
+    }
+
+    if (arg === '--output' || arg === '-o') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                outputDir: expandHome(requireValue(argv[index + 1], arg)),
+                outputProvided: true,
+            },
+        };
+    }
+
+    if (arg === '--cwd') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                cwdFilter: expandHome(requireValue(argv[index + 1], '--cwd')),
+            },
+        };
+    }
+
+    if (arg === '--project') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                projectFilter: requireValue(argv[index + 1], '--project').trim(),
+            },
+        };
+    }
+
+    if (arg === '--optimized') {
+        return {
+            index,
+            state: {
+                ...state,
+                optimized: true,
+            },
+        };
+    }
+
+    if (arg === '--tools') {
+        return {
+            index,
+            state: {
+                ...state,
+                includeTools: true,
+            },
+        };
+    }
+
+    if (arg === '--flat') {
+        return {
+            index,
+            state: {
+                ...state,
+                flat: true,
+            },
+        };
+    }
+
+    if (arg.startsWith('--output-format=')) {
+        return {
+            index,
+            state: {
+                ...state,
+                outputFormat: parseExportFormat(arg.slice('--output-format='.length)),
+            },
+        };
+    }
+
+    if (arg === '--output-format') {
+        return {
+            index: index + 1,
+            state: {
+                ...state,
+                outputFormat: parseExportFormat(requireValue(argv[index + 1], '--output-format')),
+            },
+        };
+    }
+
+    if (!arg.startsWith('-')) {
+        const threadId = parseThreadSelectionArg(arg);
+        if (!threadId) {
+            throw new CliUsageError(
+                `Unsupported positional argument: ${arg}\nExpected a Codex thread deeplink like codex://threads/<thread-id>`,
+            );
+        }
+
+        return {
+            index,
+            state: {
+                ...state,
+                threadIds: [...state.threadIds, threadId],
+            },
+        };
+    }
+
+    throw new CliUsageError(`Unknown argument: ${arg}`);
+};
+
+export const getCodexHelpText = (): string => {
+    return [
+        'Export Codex session JSONL files to Markdown or TXT.',
+        'Run with no arguments to enter interactive mode.',
+        '',
+        'Usage:',
+        '  codex-chats',
+        '  codex-chats --interactive',
+        '  codex-chats [--db FILE] [--input DIR] [--output DIR] [--cwd DIR] [--project NAME] [--optimized] [--tools] [--flat] [--output-format md|txt] [codex://threads/<thread-id> ...]',
+        '',
+        'Options:',
+        `  --db            Thread database path (default: ${DEFAULT_DB_PATH})`,
+        `  --input,  -i    Source sessions directory (default: ${DEFAULT_INPUT_DIR})`,
+        '  --output, -o    Export directory (default: ./<cwd-basename> when --cwd is set, otherwise ./exports)',
+        '  --cwd           Only export chats whose cwd matches this exact path',
+        '  --project       Only export chats whose cwd basename matches this project name',
+        '  codex://threads/<id>',
+        '                  Only export the exact threads referenced by these Codex deeplinks',
+        '  --optimized     Suppress metadata and apply token-saving text cleanup',
+        '  --tools         Include tool-call logs such as exec_command invocations',
+        '  --flat          Write all exports into one folder instead of nested subfolders',
+        '  --output-format Output file format: md or txt (default: md)',
+        '  --interactive   Start the interactive prompt flow',
+        '  --help,   -h    Show this help text',
+    ].join('\n');
+};
+
+export const parseThreadSelectionArg = (value: string): string | null => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+
+    const match = /^codex:\/\/threads\/([^/?#]+)$/u.exec(trimmed);
+    return match?.[1] ?? null;
+};
+
+export const resolveDefaultOutputDir = (cwdFilter: string | null): string => {
+    if (cwdFilter) {
+        const basename = getPortablePathBasename(cwdFilter);
+        if (basename) {
+            return path.join(process.cwd(), basename);
+        }
+    }
+
+    return DEFAULT_OUTPUT_DIR;
+};
+
+const requireValue = (value: string | undefined, flag: string): string => {
+    if (!value || value.startsWith('--')) {
+        throw new CliUsageError(`Missing value for ${flag}`);
+    }
+
+    return value;
+};
+
+const parseExportFormat = (value: string): ExportFormat => {
+    if (value === 'md' || value === 'txt') {
+        return value;
+    }
+
+    throw new CliUsageError(`Unsupported output format: ${value}`);
+};

package/src/lib/codex-exporter-db.ts

@@ -0,0 +1,320 @@
+import { Database } from 'bun:sqlite';
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import {
+    type CodexCliOptions,
+    DEFAULT_CODEX_DIR,
+    type ExportTarget,
+    type SpawnEdgeRow,
+    type ThreadData,
+    type ThreadRelations,
+    type ThreadRow,
+} from './codex-exporter-types';
+import { getPortablePathBasename } from './shared';
+
+export const loadThreadData = (dbPath: string, options: CodexCliOptions): ThreadData => {
+    const threadsById = new Map<string, ThreadRow>();
+    const parentByChildId = new Map<string, SpawnEdgeRow>();
+    const childEdgesByParentId = new Map<string, SpawnEdgeRow[]>();
+
+    let db: Database | null = null;
+
+    try {
+        db = new Database(dbPath, { readonly: true });
+
+        const threadQuery = buildThreadQuery(options);
+        const threadRows = db.query(threadQuery.sql).all(...threadQuery.params) as ThreadRow[];
+
+        for (const row of threadRows) {
+            threadsById.set(row.id, row);
+        }
+
+        const edgeQuery = buildSpawnEdgeQuery([...threadsById.keys()], options);
+        const edgeRows = db.query(edgeQuery.sql).all(...edgeQuery.params) as SpawnEdgeRow[];
+
+        for (const row of edgeRows) {
+            parentByChildId.set(row.child_thread_id, row);
+
+            const existing = childEdgesByParentId.get(row.parent_thread_id) ?? [];
+            existing.push(row);
+            childEdgesByParentId.set(row.parent_thread_id, existing);
+        }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read thread database at ${dbPath}: ${message}`);
+    } finally {
+        db?.close();
+    }
+
+    return {
+        childEdgesByParentId,
+        parentByChildId,
+        threadsById,
+    };
+};
+
+export const buildThreadQuery = (options: CodexCliOptions) => {
+    const clauses: string[] = [];
+    const params: string[] = [];
+
+    if (options.threadIds.length > 0) {
+        clauses.push(`id IN (${options.threadIds.map(() => '?').join(', ')})`);
+        params.push(...options.threadIds);
+    }
+
+    if (options.cwdFilter) {
+        clauses.push('cwd = ?');
+        params.push(options.cwdFilter);
+    }
+
+    if (options.projectFilter) {
+        clauses.push("(cwd = ? OR cwd LIKE ? ESCAPE '\\' OR cwd LIKE ? ESCAPE '\\')");
+        const projectPattern = escapeSqlLike(options.projectFilter);
+        params.push(options.projectFilter, `%/${projectPattern}`, `%\\${projectPattern}`);
+    }
+
+    return {
+        params,
+        sql: clauses.length > 0 ? `SELECT * FROM threads WHERE ${clauses.join(' AND ')}` : 'SELECT * FROM threads',
+    };
+};
+
+export const buildSpawnEdgeQuery = (threadIds: string[], options: CodexCliOptions) => {
+    const hasScopedFilters =
+        options.threadIds.length > 0 || options.cwdFilter !== null || options.projectFilter !== null;
+
+    if (!hasScopedFilters || threadIds.length === 0) {
+        return {
+            params: [] as string[],
+            sql: 'SELECT * FROM thread_spawn_edges',
+        };
+    }
+
+    const placeholders = threadIds.map(() => '?').join(', ');
+    return {
+        params: [...threadIds, ...threadIds],
+        sql: `SELECT * FROM thread_spawn_edges WHERE parent_thread_id IN (${placeholders}) OR child_thread_id IN (${placeholders})`,
+    };
+};
+
+export const findJsonlFiles = async (rootDir: string): Promise<string[]> => {
+    const entries = await readdir(rootDir, { withFileTypes: true });
+    const files: string[] = [];
+
+    for (const entry of entries) {
+        const fullPath = path.join(rootDir, entry.name);
+
+        if (entry.isDirectory()) {
+            files.push(...(await findJsonlFiles(fullPath)));
+            continue;
+        }
+
+        if (entry.isFile() && fullPath.endsWith('.jsonl')) {
+            files.push(fullPath);
+        }
+    }
+
+    files.sort();
+    return files;
+};
+
+export const shouldScanFallbackSessionFiles = (options: CodexCliOptions) => {
+    return !options.cwdFilter && !options.projectFilter && options.threadIds.length === 0;
+};
+
+export const buildExportTargets = (
+    threadData: ThreadData,
+    sessionFiles: string[],
+    options: CodexCliOptions,
+): ExportTarget[] => {
+    const targets: ExportTarget[] = [];
+    const seenSessionFiles = new Set<string>();
+    const threadOrder = new Map(options.threadIds.map((threadId, index) => [threadId, index] as const));
+
+    for (const thread of threadData.threadsById.values()) {
+        if (!matchesFilters(thread.cwd, options)) {
+            continue;
+        }
+
+        const sessionFile = path.resolve(thread.rollout_path);
+        seenSessionFiles.add(sessionFile);
+
+        targets.push({
+            fallbackReason: null,
+            outputRelativePath: toOutputRelativePath(sessionFile, options, thread.cwd),
+            relations: getRelations(thread.id, threadData),
+            sessionFile,
+            thread,
+        });
+    }
+
+    for (const sessionFile of sessionFiles) {
+        const normalized = path.resolve(sessionFile);
+        if (seenSessionFiles.has(normalized)) {
+            continue;
+        }
+
+        targets.push({
+            fallbackReason: 'missing_thread_row',
+            outputRelativePath: toOutputRelativePath(normalized, options),
+            relations: {
+                childEdges: [],
+                parentThreadId: null,
+            },
+            sessionFile: normalized,
+            thread: null,
+        });
+    }
+
+    if (options.threadIds.length > 0) {
+        targets.sort((left, right) => {
+            const leftOrder = left.thread
+                ? (threadOrder.get(left.thread.id) ?? Number.MAX_SAFE_INTEGER)
+                : Number.MAX_SAFE_INTEGER;
+            const rightOrder = right.thread
+                ? (threadOrder.get(right.thread.id) ?? Number.MAX_SAFE_INTEGER)
+                : Number.MAX_SAFE_INTEGER;
+
+            if (leftOrder !== rightOrder) {
+                return leftOrder - rightOrder;
+            }
+
+            return left.outputRelativePath.localeCompare(right.outputRelativePath);
+        });
+    } else {
+        targets.sort((left, right) => left.outputRelativePath.localeCompare(right.outputRelativePath));
+    }
+
+    return options.flat ? ensureUniqueFlatOutputPaths(targets) : targets;
+};
+
+export const matchesFilters = (
+    value: string | null | undefined,
+    options: Pick<CodexCliOptions, 'cwdFilter' | 'projectFilter'>,
+): boolean => {
+    return matchesCwdFilter(value, options.cwdFilter) && matchesProjectFilter(value, options.projectFilter);
+};
+
+export const toOutputRelativePath = (
+    sessionFile: string,
+    options: CodexCliOptions,
+    projectCwd?: string | null,
+): string => {
+    const normalized = path.resolve(sessionFile);
+    const inputRoot = path.resolve(options.inputDir);
+    const codexRoot = path.resolve(DEFAULT_CODEX_DIR);
+    const extension = options.outputFormat === 'txt' ? '.txt' : '.md';
+    const flatName = toFlatFileName(normalized, extension, projectCwd);
+
+    if (options.flat) {
+        return flatName;
+    }
+
+    if (normalized.startsWith(`${inputRoot}${path.sep}`)) {
+        return path.relative(inputRoot, normalized).replace(/\.jsonl$/i, extension);
+    }
+
+    if (normalized.startsWith(`${codexRoot}${path.sep}`)) {
+        return path.relative(codexRoot, normalized).replace(/\.jsonl$/i, extension);
+    }
+
+    return path.basename(normalized).replace(/\.jsonl$/i, extension);
+};
+
+export const toCodexRelativePath = (targetPath: string): string => {
+    const codexRoot = path.resolve(DEFAULT_CODEX_DIR);
+    const normalized = path.resolve(targetPath);
+
+    if (normalized.startsWith(`${codexRoot}${path.sep}`)) {
+        return path.relative(codexRoot, normalized);
+    }
+
+    return normalized;
+};
+
+const escapeSqlLike = (value: string) => {
+    return value.replace(/([\\%_])/g, '\\$1');
+};
+
+const getRelations = (threadId: string, threadData: ThreadData): ThreadRelations => {
+    const parentEdge = threadData.parentByChildId.get(threadId) ?? null;
+    const childEdges = [...(threadData.childEdgesByParentId.get(threadId) ?? [])].sort((left, right) =>
+        left.child_thread_id.localeCompare(right.child_thread_id),
+    );
+
+    return {
+        childEdges,
+        parentThreadId: parentEdge?.parent_thread_id ?? null,
+    };
+};
+
+const matchesCwdFilter = (value: string | null | undefined, cwdFilter: string | null): boolean => {
+    if (!cwdFilter) {
+        return true;
+    }
+
+    return value === cwdFilter;
+};
+
+const matchesProjectFilter = (value: string | null | undefined, projectFilter: string | null): boolean => {
+    if (!projectFilter) {
+        return true;
+    }
+
+    if (!value) {
+        return false;
+    }
+
+    return getPortablePathBasename(value) === projectFilter;
+};
+
+const toFlatFileName = (sessionFile: string, extension: string, projectCwd?: string | null): string => {
+    const normalized = path.resolve(sessionFile);
+    const codexRoot = path.resolve(DEFAULT_CODEX_DIR);
+    const relative = normalized.startsWith(`${codexRoot}${path.sep}`)
+        ? path.relative(codexRoot, normalized)
+        : path.basename(normalized);
+
+    const flattened = relative.replace(/[\\/]/g, '__').replace(/\.jsonl$/i, extension);
+
+    if (!projectCwd) {
+        return flattened;
+    }
+
+    const portableProjectName = getPortablePathBasename(projectCwd);
+    if (!portableProjectName) {
+        return flattened;
+    }
+
+    return `${portableProjectName}${extension}`;
+};
+
+const ensureUniqueFlatOutputPaths = (targets: ExportTarget[]): ExportTarget[] => {
+    const counts = new Map<string, number>();
+    for (const target of targets) {
+        counts.set(target.outputRelativePath, (counts.get(target.outputRelativePath) ?? 0) + 1);
+    }
+
+    return targets.map((target) => {
+        if ((counts.get(target.outputRelativePath) ?? 0) < 2) {
+            return target;
+        }
+
+        const suffix = getFlatCollisionSuffix(target);
+        const extension = path.extname(target.outputRelativePath);
+        const basename = extension ? target.outputRelativePath.slice(0, -extension.length) : target.outputRelativePath;
+
+        return {
+            ...target,
+            outputRelativePath: `${basename}__${suffix}${extension}`,
+        };
+    });
+};
+
+const getFlatCollisionSuffix = (target: ExportTarget): string => {
+    if (target.thread?.id) {
+        return target.thread.id.slice(0, 8);
+    }
+
+    return path.basename(target.sessionFile, '.jsonl').slice(-8);
+};