spiracha 1.0.0

package/AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md
+
+## Purpose
+
+This repo exports local Codex chats and Claude Code transcripts to Markdown or plain text.
+
+Main entrypoints:
+- `bun start ...` for Codex chat export
+- `bun start` for interactive export mode
+- `bun run export:claude -- ...` for Claude transcript export
+- `bun run mcp` for the MCP server used by the local Codex plugin
+- published package goal:
+  - `bunx codex-chats`
+  - `bunx codex-chats ...`
+  - `bunx codex-chats-claude ...`
+
+## Conventions and Rules
+
+- Always use `bun` and `bunx`, HARD BAN on: `npm` unless absolutely necessary.
+- Prefer `Bun.file()` instead of `fs` whenever possible.
+- Kill any browser instance you start or stray `bun`, `node` processes after you are done. Never leave it running.
+- Prefer arrow functions to classical functions, and `type` over `interface` in TS.
+- Fixes are made using TDD approach.
+- `bun format` and `bun typecheck` should always be ran at the end of your completion, if you introduced any warnings or errors clean them up yourself before you complete.
+- NEVER disable a biome rule or TS rule without explicit permission from the user.
+- If you believe the code you are changing requires some clarification for future AI agents to understand why the change was made, add a brief comment.
+- Do NOT use decorative section headers made of repeated characters (e.g. `// -----`, `// =====`, etc.).
+- Use `it('should...')` style tests.
+- Unit-tests always live in the same folder as their implementation, never in the `test` folder.
+
+## Working Rules
+
+- Use `rtk` as the default wrapper for shell commands that produce meaningful stdout or stderr.
+- Prefer `bun test` for verification. Run it after non-trivial changes.
+- When changing package/distribution behavior, also run a local packed-tarball smoke test.
+- When changing the interactive flow, validate it in a real TTY session; piped stdin is not a reliable substitute.
+- Use `apply_patch` for manual edits.
+- Keep output compatibility stable. The exported transcript format is user-facing.
+- Preserve the behavior of existing flags unless the task explicitly changes CLI semantics.
+
+## Architecture
+
+Codex exporter modules:
+- `src/lib/codex-exporter.ts`
+  - top-level orchestration and public barrel exports
+- `src/lib/codex-exporter-cli.ts`
+  - CLI parsing, help text, deeplink parsing, default output-dir resolution
+- `src/lib/codex-exporter-db.ts`
+  - SQLite queries, fallback session discovery, filter matching, export target construction
+- `src/lib/codex-exporter-transcript.ts`
+  - JSONL transcript parsing, metadata extraction, message/tool rendering
+- `src/lib/codex-exporter-types.ts`
+  - shared Codex exporter types and default path constants
+
+Other important files:
+- `src/lib/claude-exporter.ts`
+  - Claude transcript export pipeline
+- `src/mcp-server.ts`
+  - MCP server exposing `export_codex_chats` and `export_claude_transcript`
+- `plugins/codex-chats-export/`
+  - local Codex plugin manifest, skill, and MCP wiring
+
+## Test Strategy
+
+Current tests cover:
+- exporter end-to-end behavior for Codex and Claude
+- Codex CLI parsing helpers
+- interactive-mode inference helpers
+- transcript formatting helpers
+- MCP stdio protocol round-trips using the real server process
+- type-checking via `bun run typecheck`
+
+When changing risky areas:
+- CLI changes: update/add tests in `src/lib/codex-exporter-cli.test.ts`
+- transcript parsing/rendering: update/add tests in `src/lib/codex-exporter-transcript.test.ts`
+- DB/filter/target logic: prefer focused unit tests against `src/lib/codex-exporter-db.ts`
+- MCP contract changes: update `src/mcp-server.test.ts`
+
+## Common Commands
+
+```bash
+rtk bun test
+rtk bun run typecheck
+rtk bun run build
+rtk bun run test:perf
+rtk bun start
+rtk bun start -- --help
+rtk bun start --interactive
+rtk bun run export:claude -- --help
+rtk bun run mcp
+```
+
+Packed tarball smoke test:
+
+```bash
+rtk bun pm pack
+package_tgz="$PWD/codex-chats-<version>.tgz"
+tmp_dir=$(mktemp -d)
+cd "$tmp_dir"
+printf '{"name":"codex-chats-smoke","private":true}\n' > package.json
+rtk bun add "$package_tgz"
+rtk bunx codex-chats --help
+rtk bunx codex-chats-claude --help
+```
+
+Example Codex export:
+
+```bash
+rtk bunx codex-chats
+rtk bunx codex-chats codex://threads/<thread-id> --optimized
+rtk bun start --tools --project summer
+rtk bun start codex://threads/<thread-id> --output-format txt
+```
+
+Example Claude export:
+
+```bash
+rtk bunx codex-chats-claude /path/to/transcript --output-format txt
+rtk bun run export:claude -- /path/to/export-dir --output-format txt
+```
+
+## Notes
+
+- `--project` matches the final `cwd` path segment for both POSIX and Windows-style paths, not the full path.
+- Running `codex-chats` or `bun start` with no args enters interactive mode.
+- Codex MCP exports must be scoped by at least one of `deeplinks`, `project`, or `cwd`.
+- `txt` output is intentionally real plain text, not Markdown with a `.txt` extension.
+- The published package is Bun-first. `bin` entrypoints target Bun shebang execution.

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Ragaeeb Haq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# spiracha
+
+[![npm version](https://img.shields.io/npm/v/spiracha?label=npm)](https://www.npmjs.com/package/spiracha)
+[![downloads](https://img.shields.io/npm/dm/spiracha?label=downloads)](https://www.npmjs.com/package/spiracha)
+[![license](https://img.shields.io/npm/l/spiracha)](LICENSE.md)
+[![runtime](https://img.shields.io/badge/runtime-Bun-000000?logo=bun)](https://bun.sh)
+
+Export local Codex chats and Claude Code transcripts to Markdown or plain text.
+
+## Quick Start
+
+For repo-local development:
+
+```bash
+bun start
+```
+
+Published package usage, once the package is available on npm:
+
+```bash
+bunx spiracha
+bunx spiracha claude /path/to/session-export.jsonl --output-format txt
+```
+
+## Features
+
+- Export Codex session transcripts from local `.codex` history
+- Filter Codex exports by:
+  - exact `cwd`
+  - project basename via `--project`
+  - specific thread deeplinks like `codex://threads/<id>`
+- Include command logs with `--tools`
+- Write Markdown or real plain-text output with `--output-format md|txt`
+- Export Claude Code transcript `.jsonl` files or export directories
+- Run the same export flows through an MCP server and a local Codex plugin
+
+## Install
+
+```bash
+bun install
+```
+
+For package use after publish, no local install is required:
+
+```bash
+bunx spiracha --help
+```
+
+## Usage
+
+### Codex exports
+
+Package entrypoint:
+
+```bash
+bunx spiracha [options] [codex://threads/<id> ...]
+bunx spiracha codex [options] [codex://threads/<id> ...]
+```
+
+With no arguments, `spiracha` starts in interactive mode and asks what you want to export.
+
+Examples:
+
+```bash
+bunx spiracha
+bunx spiracha --interactive
+bunx spiracha --project summer
+bunx spiracha --tools --project summer
+bunx spiracha codex://threads/019da28f-ee5b-7881-afe0-68b3d3bd2c77
+bunx spiracha codex://threads/019da28f-ee5b-7881-afe0-68b3d3bd2c77 --output-format txt
+bunx spiracha --cwd ~/workspace/reversed/summer --flat
+```
+
+Important flags:
+- no args: start interactive mode
+- `--interactive`: force the interactive prompt flow
+- `--project <name>`: matches the final `cwd` path segment for both POSIX and Windows-style paths
+- `--cwd <path>`: exact cwd match
+- `--tools`: include `exec_command` call logs and summaries
+- `--optimized`: compact transcript output
+- `--flat`: write files into a single output folder
+- `--output-format md|txt`: output as Markdown or plain text
+
+### Claude exports
+
+```bash
+bunx spiracha claude <input-path> [options]
+```
+
+Examples:
+
+```bash
+bunx spiracha claude /path/to/session.jsonl
+bunx spiracha claude /path/to/export-dir --tools
+bunx spiracha claude /path/to/export-dir --output-format txt
+```
+
+Repo-local equivalents remain available during development:
+
+```bash
+bun start
+bun start --interactive
+bun start ...
+bun run export:claude -- ...
+```
+
+Legacy aliases remain available for compatibility:
+
+```bash
+bunx codex-chats
+bunx codex-chats-claude
+```
+
+## MCP server
+
+Run the MCP server with:
+
+```bash
+bun run mcp
+```
+
+Exposed tools:
+- `export_codex_chats`
+- `export_claude_transcript`
+
+The local plugin lives in [plugins/codex-chats-export](~/workspace/codex-chats/plugins/codex-chats-export) and is registered through [plugins/codex-chats-export/.mcp.json](~/workspace/codex-chats/plugins/codex-chats-export/.mcp.json).
+
+## Development
+
+Useful commands:
+
+```bash
+bun test
+bun run typecheck
+bun run build
+bun run test:perf
+bun start
+bun start --interactive
+bun start -- --help
+bun run export:claude -- --help
+bun run mcp
+```
+
+Packed-tarball smoke test before publishing:
+
+```bash
+bun pm pack
+package_tgz="$PWD/codex-chats-<version>.tgz"
+tmp_dir=$(mktemp -d)
+cd "$tmp_dir"
+printf '{"name":"codex-chats-smoke","private":true}\n' > package.json
+bun add "$package_tgz"
+bunx spiracha --help
+bunx spiracha claude --help
+bunx codex-chats --help
+bunx codex-chats-claude --help
+```
+
+## Project Layout
+
+- `src/export-chats.ts`: Codex CLI wrapper
+- `src/export-claude.ts`: Claude CLI wrapper
+- `src/mcp-server.ts`: MCP server entrypoint
+- `src/lib/codex-exporter-*.ts`: Codex exporter modules
+- `src/lib/claude-exporter.ts`: Claude exporter implementation
+- `plugins/codex-chats-export/`: local Codex plugin bundle
+
+## Testing
+
+The test suite includes:
+- Codex exporter end-to-end coverage
+- Claude exporter end-to-end coverage
+- Codex CLI helper tests
+- transcript rendering helper tests
+- MCP stdio protocol round-trip tests
+- local packaging should be smoke-tested with a packed tarball before publishing
+
+Run:
+
+```bash
+bun test
+```

package/package.json

@@ -0,0 +1,70 @@
+{
+    "author": {
+        "name": "Ragaeeb Haq",
+        "url": "https://github.com/ragaeeb"
+    },
+    "bin": {
+        "codex-chats": "./src/export-chats.ts",
+        "codex-chats-claude": "./src/export-claude.ts",
+        "spiracha": "./src/spiracha.ts"
+    },
+    "bugs": {
+        "url": "https://github.com/ragaeeb/spiracha/issues"
+    },
+    "dependencies": {
+        "@inquirer/prompts": "^8.4.2",
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "zod": "^4.4.3"
+    },
+    "description": "Export local Codex chats and Claude Code transcripts to Markdown or plain text.",
+    "devDependencies": {
+        "@types/bun": "^1.3.13",
+        "@types/node": "^25.6.2",
+        "typescript": "^6.0.3"
+    },
+    "engines": {
+        "bun": ">=1.3.13"
+    },
+    "files": [
+        "src/export-chats.ts",
+        "src/export-claude.ts",
+        "src/mcp-server.ts",
+        "src/spiracha.ts",
+        "src/lib/claude-exporter.ts",
+        "src/lib/codex-exporter-cli.ts",
+        "src/lib/codex-exporter-db.ts",
+        "src/lib/codex-exporter-transcript.ts",
+        "src/lib/codex-exporter-types.ts",
+        "src/lib/codex-exporter.ts",
+        "src/lib/interactive-cli.ts",
+        "src/lib/shared.ts",
+        "README.md",
+        "AGENTS.md"
+    ],
+    "homepage": "https://github.com/ragaeeb/spiracha#readme",
+    "keywords": [
+        "codex",
+        "claude",
+        "transcripts",
+        "export",
+        "markdown",
+        "bun"
+    ],
+    "license": "MIT",
+    "name": "spiracha",
+    "packageManager": "bun@1.3.13",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ragaeeb/spiracha.git"
+    },
+    "scripts": {
+        "build": "bun run typecheck",
+        "export:claude": "bun run ./src/export-claude.ts",
+        "format": "biome check . --write && biome lint . --write",
+        "mcp": "bun run ./src/mcp-server.ts",
+        "start": "bun run ./src/export-chats.ts",
+        "typecheck": "bunx tsc --noEmit"
+    },
+    "type": "module",
+    "version": "1.0.0"
+}

package/src/export-chats.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { stdin as input, stdout as output } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { getCodexHelpText, parseCodexCliArgs, runCodexExport } from './lib/codex-exporter';
+import { runInteractiveExport } from './lib/interactive-cli';
+import { CliUsageError } from './lib/shared';
+
+export const runExportChatsCli = async (argv = process.argv.slice(2)): Promise<void> => {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(getCodexHelpText());
+        return;
+    }
+
+    try {
+        if (shouldRunInteractive(argv)) {
+            await runInteractiveCliFlow();
+            return;
+        }
+
+        await runCodexCliFlow(argv);
+    } catch (error) {
+        if (error instanceof CliUsageError) {
+            console.error(error.message);
+            console.error('');
+            console.error(getCodexHelpText());
+            process.exit(1);
+        }
+
+        if (error instanceof Error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+
+        throw error;
+    }
+};
+
+const shouldRunInteractive = (argv: string[]): boolean => {
+    return argv.length === 0 || argv.includes('--interactive');
+};
+
+const runInteractiveCliFlow = async (): Promise<void> => {
+    const result = await runInteractiveExport();
+    const targetFolder = await printInteractiveExportResult(result);
+    await maybeOpenExportFolder(targetFolder);
+};
+
+const runCodexCliFlow = async (argv: string[]): Promise<void> => {
+    const options = parseCodexCliArgs(argv);
+    const result = await runCodexExport(options);
+    printCodexExportResult(result);
+};
+
+const printInteractiveExportResult = async (
+    result: Awaited<ReturnType<typeof runInteractiveExport>>,
+): Promise<string> => {
+    if (result.mode === 'claude') {
+        console.log(`Exported ${result.sourcePath} -> ${result.outputPath}`);
+        return resolveExportFolder(result.outputPath);
+    }
+
+    printCodexExportFiles(result.files);
+    printMissingThreadWarnings(result.missingThreadIds);
+    console.log(`Done. Exported ${result.exportedCount} chat(s) to ${result.outputDir}`);
+    return result.outputDir;
+};
+
+const printCodexExportResult = (result: Awaited<ReturnType<typeof runCodexExport>>): void => {
+    printCodexExportFiles(result.files);
+    printMissingThreadWarnings(result.missingThreadIds);
+    console.log(`Done. Exported ${result.exportedCount} chat(s) to ${result.outputDir}`);
+};
+
+const printCodexExportFiles = (files: Awaited<ReturnType<typeof runCodexExport>>['files']): void => {
+    for (const file of files) {
+        console.log(`Exported ${file.sourcePath} -> ${file.outputPath}`);
+    }
+};
+
+const printMissingThreadWarnings = (missingThreadIds: string[]): void => {
+    if (missingThreadIds.length > 0) {
+        console.warn(
+            `Warning: ${missingThreadIds.length} requested thread(s) were not found: ${missingThreadIds.join(', ')}`,
+        );
+    }
+};
+
+const maybeOpenExportFolder = async (targetFolder: string): Promise<void> => {
+    const rl = createInterface({ input, output });
+    try {
+        while (true) {
+            const answer = (await rl.question('Open the exported folder now? [y/N]: ')).trim().toLowerCase();
+            if (!answer || answer === 'n' || answer === 'no') {
+                return;
+            }
+            if (answer === 'y' || answer === 'yes') {
+                await openPathNatively(targetFolder);
+                return;
+            }
+            console.log('Please answer y or n.');
+        }
+    } finally {
+        rl.close();
+    }
+};
+
+const resolveExportFolder = async (targetPath: string): Promise<string> => {
+    const stats = await lstat(targetPath).catch(() => null);
+    if (stats?.isDirectory()) {
+        return targetPath;
+    }
+    return path.dirname(targetPath);
+};
+
+const openPathNatively = async (targetPath: string): Promise<void> => {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
+
+    const proc = Bun.spawn([command, targetPath], {
+        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 ${targetPath} with ${command}: ${errorText.trim() || `exit code ${exitCode}`}`);
+    }
+};
+
+if (import.meta.main) {
+    await runExportChatsCli();
+}

package/src/export-claude.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+
+import { getClaudeHelpText, parseClaudeCliArgs, runClaudeExport } from './lib/claude-exporter';
+import { CliUsageError } from './lib/shared';
+
+export const runExportClaudeCli = async (argv = process.argv.slice(2)): Promise<void> => {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(getClaudeHelpText());
+        return;
+    }
+
+    try {
+        const options = parseClaudeCliArgs(argv);
+        const result = await runClaudeExport(options);
+
+        console.log(`Exported ${result.sourcePath} -> ${result.outputPath}`);
+    } catch (error) {
+        if (error instanceof CliUsageError) {
+            console.error(error.message);
+            console.error('');
+            console.error(getClaudeHelpText());
+            process.exit(1);
+        }
+
+        if (error instanceof Error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+
+        throw error;
+    }
+};
+
+if (import.meta.main) {
+    await runExportClaudeCli();
+}