ccexport 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ccc4798123b459b9c2f9eb8637d17c28d5168ac7f0ea965c23b56543636f832e
+  data.tar.gz: 30e8610415bf25386cd49dfec6a0e6f4b0ad8bfa401d1968dfdea4cff50443a9
+SHA512:
+  metadata.gz: f33cbe1749351761a15927f669728b4fde3ff8e0c4043691b8ce53dd4ca990e14aff410d241e5269639661d587668e8f348d6b01cc1bfd73211d40b13a3da256
+  data.tar.gz: d687d278ab543a97b1ec4e875654029c922f1a069aa588f998977181fb27c2778296288e1009e8afdc42e9098f4a0997c8047cddeaf40919c36faa23b95cfdf7

data/.gitignore

@@ -0,0 +1,7 @@
+claude-conversations/
+docs/
+.DS_Store
+TEST.*
+
+# Gem build artifacts
+*.gem

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-08-17
+
+### Added
+- Initial release of ccexport gem
+- Export Claude Code conversations from JSONL session files to Markdown and HTML
+- Multiple HTML templates: default, github, solarized with dark/light mode support
+- Comprehensive syntax highlighting with Prism.js for Ruby, JavaScript, Python, TypeScript, JSON, Markdown, YAML, Bash
+- TruffleHog integration for secret detection and redaction
+- Date filtering and custom output paths
+- HTML preview generation with automatic browser opening
+- Command-line interface with extensive options
+- Support for both single session and multi-session exports
+- Path relativization for project files
+- Comprehensive test suite with RSpec

data/CLAUDE.md

@@ -0,0 +1,156 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/claude_conversation_exporter_spec.rb
+
+# Run tests for a specific feature
+bundle exec rspec spec/secret_detection_spec.rb
+
+# Run tests with documentation output
+bundle exec rspec --format documentation
+```
+
+### Installation & Dependencies
+```bash
+# Install Ruby dependencies
+bundle install
+
+# Install TruffleHog (required for secret detection)
+brew install trufflehog
+
+# Install cmark-gfm (required for HTML preview generation)
+brew install cmark-gfm
+```
+
+### Running the Tool
+```bash
+# Basic export (all conversations)
+./bin/ccexport
+
+# Export with HTML preview
+./bin/ccexport --preview
+
+# Export specific date range
+./bin/ccexport --from 2024-01-01 --to 2024-01-31 --preview
+
+# Generate VIBE examples for all templates
+./generate_vibe_samples
+```
+
+## Architecture Overview
+
+### Core Components
+
+**ClaudeConversationExporter** (`lib/claude_conversation_exporter.rb`)
+- Main class handling conversation discovery, parsing, and export
+- Uses class methods for simple API: `ClaudeConversationExporter.export`
+- Handles both single session and multi-session exports
+- Integrates secret detection, path relativization, and HTML generation
+
+**TruffleHogSecretDetector** (`lib/secret_detector.rb`) 
+- Wrapper around TruffleHog external command for secret detection
+- Uses temporary files and JSON parsing to interface with TruffleHog
+- Provides `scan()` and `redact()` methods with Finding objects
+- Backward compatible with previous SecretDetector interface
+
+**CLI Interface** (`bin/ccexport`)
+- OptionParser-based command line interface
+- Supports date filtering, custom paths, templates, and preview generation
+- Handles both directory scanning and specific JSONL file processing
+
+### Data Flow
+
+1. **Discovery**: Finds Claude Code session files (`.jsonl`) in `~/.claude/projects/` subdirectories
+2. **Parsing**: Reads JSONL files line by line, extracting messages and metadata
+3. **Processing**: 
+   - Pairs tool_use with tool_result messages across message boundaries
+   - Filters messages by date range if specified
+   - Applies specialized formatting for different tool types (Write, Bash, Edit, TodoWrite)
+4. **Path Relativization**: Converts absolute project paths to relative paths throughout content
+5. **Secret Detection**: Scans entire final markdown content with TruffleHog and redacts findings
+6. **Output**: Generates markdown and optional HTML preview
+
+### Template System
+
+**Template Location**: `lib/templates/*.html.erb`
+- `default.html.erb`: Clean modern styling with warm colors
+- `github.html.erb`: GitHub-style rendering  
+- `solarized.html.erb`: Solarized color scheme with automatic dark/light mode detection and clickable theme toggle
+
+**Template Features**:
+- ERB templating with `<%= content %>` and `<%= title %>` variables
+- Embedded Prism.js syntax highlighting from `lib/assets/`
+- CSS custom properties for theme consistency
+- Responsive design with proper mobile support
+
+### Syntax Highlighting (Prism.js)
+
+**Current Language Support**: Markup/HTML, CSS, C-like, JavaScript, Ruby, Python, Markdown, TypeScript, JSON, YAML, Bash
+
+**Adding New Languages**:
+1. Download language component from CDN:
+   ```bash
+   curl -s "https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-LANGUAGE.min.js" \
+     -o lib/assets/prism-LANGUAGE.js
+   ```
+
+2. Add component filename to `include_prism` method in `lib/claude_conversation_exporter.rb`:
+   ```ruby
+   language_components = %w[
+     prism-python.js
+     prism-markdown.js
+     prism-typescript.js
+     prism-json.js
+     prism-yaml.js
+     prism-bash.js
+     prism-LANGUAGE.js  # <- Add new language here
+   ]
+   ```
+
+3. Update README.md language list if needed
+
+**Language Component Files**: Kept separate in `lib/assets/prism-*.js` for maintainability. The `include_prism` method dynamically loads and concatenates all components.
+
+### Message Processing Pipeline
+
+**Tool Pairing Logic**: Complex cross-message matching where `tool_use` messages are paired with subsequent `tool_result` messages based on tool ID, even when they appear in separate user/assistant message blocks.
+
+**Content Extraction**: Handles different Claude message content types:
+- `text`: Plain text content
+- `tool_use`: Formatted as collapsible sections with syntax highlighting
+- `thinking`: Displayed as blockquotes with special emoji indicators
+
+**Filtering**: System-generated messages and leaf summaries are filtered out, with comprehensive logging in `*_skipped.jsonl` files.
+
+## Special Considerations
+
+### Secret Detection
+- Runs TruffleHog on final markdown content (not individual messages)
+- Creates `*_secrets.jsonl` logs with context information
+- Uses `[REDACTED]` replacement strategy
+- External dependency on `trufflehog` command
+
+### Claude Code Session Discovery
+- Automatically discovers sessions in `~/.claude/projects/` subdirectories
+- Handles complex project path mappings and multiple session files per project
+- Session directory structure: `~/.claude/projects/{escaped-project-path}/`
+
+### VIBE Examples
+- `VIBE.md` and `VIBE_*.html`: Limited examples (67 messages) for easy browsing
+- `VIBE_full.md` and `VIBE_full.html`: Complete conversation (3,806 messages) demonstrating scalability
+- `./generate_vibe_samples` script regenerates all template examples automatically
+
+### Testing Strategy
+- 96 RSpec tests covering all major functionality
+- Test fixtures in `spec/fixtures/` with real JSONL data samples
+- Mocking of external dependencies (TruffleHog, cmark-gfm, system commands)
+- Comprehensive secret detection testing with realistic secret formats

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ccexport.gemspec
+gemspec
+
+gem "rake", "~> 13.0"

data/Gemfile.lock

@@ -0,0 +1,36 @@
+PATH
+  remote: .
+  specs:
+    ccexport (0.1.0)
+      json (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.6.2)
+    json (2.13.2)
+    rake (13.3.0)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+
+PLATFORMS
+  arm64-darwin-24
+
+DEPENDENCIES
+  ccexport!
+  rake (~> 13.0)
+  rspec (~> 3.12)
+
+BUNDLED WITH
+   2.6.7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claude Code Conversation Exporter
+
+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.