claude-session-share 1.0.0 → 1.2.0

package/README.md

@@ -1,21 +1,18 @@
 # claude-session-share
 
-> **MCP server for sharing Claude Code sessions via GitHub Gist with automatic privacy protection**
-
-Share your Claude Code conversations effortlessly while keeping your private data safe. This MCP server enables you to export sessions to shareable GitHub Gist links and import them back—all through natural language.
+MCP server for sharing Claude Code sessions via GitHub Gist with automatic privacy protection.
 
 [![npm version](https://badge.fury.io/js/claude-session-share.svg)](https://www.npmjs.com/package/claude-session-share)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## ✨ Features
+## Features
 
-- **🔗 One-Click Sharing** - Export sessions to GitHub Gist with a simple command
-- **🔒 Privacy First** - Automatically strips thinking blocks, sanitizes paths, and redacts secrets
-- **📥 Seamless Import** - Import shared sessions that work exactly like native Claude Code sessions
-- **💬 Natural Language** - Just ask Claude to "share my session" or "import from [link]"
-- **🔄 Full Compatibility** - Imported sessions appear in `claude --resume` and preserve conversation context
+- **One-Click Sharing** - Export sessions to GitHub Gist through natural language
+- **Privacy First** - Automatically strips thinking blocks, sanitizes paths, and redacts secrets
+- **Seamless Import** - Import shared sessions that work exactly like native Claude Code sessions
+- **Full Compatibility** - Imported sessions appear in `claude --resume`
 
-## 📦 Installation
+## Installation
 
 ### Prerequisites
 
@@ -23,27 +20,16 @@ Share your Claude Code conversations effortlessly while keeping your private dat
 - Claude Code CLI
 - GitHub Personal Access Token with `gist` scope
 
-### Install via npm
-
-```bash
-npm install -g claude-session-share
-```
-
 ### Setup GitHub Token
 
 1. Go to [GitHub Settings > Personal Access Tokens](https://github.com/settings/tokens)
 2. Click "Generate new token (classic)"
-3. Give it a name like "Claude Session Share"
-4. Check the **`gist`** scope
-5. Generate and copy the token
-
-## ⚙️ Configuration
+3. Check the **`gist`** scope
+4. Generate and copy the token
 
-Add the MCP server to your Claude Code configuration:
+### Configure MCP Server
 
-### Option 1: User Config (Recommended)
-
-Create or edit `~/.claude/mcp.json`:
+Add to `~/.claude/mcp.json`:
 
 ```json
 {
@@ -59,24 +45,19 @@ Create or edit `~/.claude/mcp.json`:
 }
 ```
 
-### Option 2: Project-Specific Config
-
-Create `.mcp.json` in your project directory with the same structure.
-
 ### Verify Installation
 
 ```bash
-# Check if the MCP server is recognized
 claude  # Start Claude Code
-# Then type: /mcp
+# Type: /mcp
 # You should see "claude-session-share" in the list
 ```
 
-## 🚀 Usage
+## Usage
 
-### Sharing a Session
+### Share a Session
 
-In any Claude Code conversation, simply say:
+In any Claude Code conversation:
 
 ```
 "Share my current session to GitHub Gist"
@@ -85,229 +66,71 @@ In any Claude Code conversation, simply say:
 Claude will:
 1. Find your current session
 2. Remove thinking blocks and sanitize paths/secrets
-3. Upload to a secret (unlisted) GitHub Gist
+3. Upload to a secret GitHub Gist
 4. Return a shareable link
 
-**Example output:**
-```
-✓ Session shared successfully!
-Link: https://gist.github.com/username/abc123...
+### Import a Session
 
-Share this link with anyone. They can import it with:
-"Import session from https://gist.github.com/username/abc123..."
 ```
-
-### Importing a Session
-
-To import a shared session:
-
-```
-"Import this session: https://gist.github.com/username/abc123..."
+"Import this session: https://gist.github.com/username/abc123"
 ```
 
-Claude will:
-1. Fetch the session from the Gist
-2. Remap UUIDs to avoid conflicts
-3. Write to your local `.claude/projects/` directory
-4. Make it available for resuming
-
-### Resuming an Imported Session
+### Resume an Imported Session
 
 ```bash
-cd your-project-directory
 claude --resume
 # Select the imported session from the list
 ```
 
-The imported session works exactly like a native Claude Code session—full conversation history, no thinking blocks, perfect privacy.
+Or directly:
+```bash
+claude --resume <session-id>
+```
 
-## 🔐 Privacy Protection
+## Privacy Protection
 
 Every shared session is automatically sanitized:
 
-### ✅ What Gets Removed/Sanitized
-
-- **Thinking Blocks** - Internal reasoning stripped completely
-- **Absolute Paths** - `/Users/you/project/file.ts` → `file.ts`
-- **API Keys** - `sk_test_abc123`, `ghp_token`, AWS keys → `[REDACTED]`
-- **Tokens** - Bearer tokens, OAuth tokens → `[REDACTED]`
-- **Secrets** - Environment variables, passwords (key=value format) → `[REDACTED]`
-
-### ✅ What Gets Preserved
+### Removed/Sanitized
+- Thinking blocks (internal reasoning)
+- Absolute paths → relative paths
+- API keys, tokens, secrets → `[REDACTED]`
 
+### Preserved
 - Conversation flow and context
-- Code examples and explanations
-- File names and relative paths
+- Code examples
+- Relative file paths
 - Tool use history
-- UUIDs and message chains (remapped on import)
-
-### Known Limitations
 
-- Passwords in connection strings (e.g., `postgresql://user:pass@host/db`) are not detected
-- Secrets in natural language (not key=value format) may not be redacted
-- These tradeoffs prevent false positives on legitimate content
-
-## 📚 MCP Tools Reference
-
-The server provides two MCP tools:
+## MCP Tools
 
 ### `share_session`
-
-Exports the current session to GitHub Gist.
-
-**Parameters:**
-- `sessionPath` (optional) - Path to session file (defaults to most recent)
-
-**Returns:**
-- `gistUrl` - Shareable GitHub Gist URL
-- `messageCount` - Number of messages exported
+Exports current session to GitHub Gist.
 
 ### `import_session`
+Imports session from GitHub Gist URL.
 
-Imports a session from a GitHub Gist.
+## Troubleshooting
 
-**Parameters:**
-- `gistUrl` - GitHub Gist URL (e.g., `https://gist.github.com/user/abc123`)
-- `projectPath` (optional) - Local project directory (defaults to current directory)
+### "Not authenticated" Error
+Ensure `GITHUB_TOKEN` is set in MCP configuration.
 
-**Returns:**
-- `sessionPath` - Path to imported session file
-- `sessionId` - New session ID
-- `messageCount` - Number of messages imported
+### Imported Session Doesn't Appear
+Restart Claude Code to refresh the session list.
 
-## 🛠️ Development
+### MCP Server Not Listed
+Verify `~/.claude/mcp.json` and restart Claude Code.
 
-### Clone and Setup
+## Development
 
 ```bash
 git clone https://github.com/OmkarKovvali/claude-session-share.git
 cd claude-session-share
 npm install
-```
-
-### Build
-
-```bash
 npm run build
-```
-
-### Run Tests
-
-```bash
 npm test
-# 337 tests with full coverage
-```
-
-### Project Structure
-
-```
-claude-session-share/
-├── src/
-│   ├── index.ts                 # MCP server entry point
-│   ├── gist/                    # GitHub Gist integration
-│   ├── sanitization/            # Privacy protection
-│   ├── services/                # Share/import orchestration
-│   ├── session/                 # Session read/write
-│   └── utils/                   # UUID remapping, etc.
-├── dist/                        # Compiled output
-├── .planning/                   # Project planning docs
-└── package.json
 ```
 
-## 🧪 Testing
-
-The project includes comprehensive test coverage:
-
-- **Unit Tests** - All modules tested individually
-- **Integration Tests** - Service orchestration verified
-- **E2E Tests** - Full share→import→resume workflow validated
-- **Real API Tests** - GitHub Gist integration tested with actual API
-
-Run tests:
-```bash
-npm test                    # All tests
-npm test -- session-reader  # Specific test file
-```
-
-## 🤝 Contributing
-
-Contributions welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-### Code Style
-
-- TypeScript with strict mode
-- ESM modules
-- Functional programming style (immutable transformations)
-- Comprehensive tests for new features
-
-## 📋 Roadmap
-
-- [x] Core share/import functionality
-- [x] Privacy sanitization
-- [x] MCP server integration
-- [x] End-to-end testing
-- [ ] Web interface for browsing shared sessions
-- [ ] Session versioning and updates
-- [ ] Organization/team sharing features
-- [ ] Custom sanitization rules
-
-## 🐛 Troubleshooting
-
-### "Not authenticated" Error
-
-Make sure your `GITHUB_TOKEN` is set in the MCP configuration:
-```json
-"env": {
-  "GITHUB_TOKEN": "ghp_your_token_here"
-}
-```
-
-### "No sessions found" Error
-
-Ensure you're in a directory with an active Claude Code session. Sessions are stored in `~/.claude/projects/`.
-
-### Imported Session Doesn't Appear
-
-Check that the session was written to the correct location:
-```bash
-ls -la ~/.claude/projects/*/
-```
-
-Each project directory should have a `.jsonl` file—that's your session.
-
-### MCP Server Not Listed
-
-Verify your MCP configuration:
-```bash
-cat ~/.claude/mcp.json
-```
-
-Then restart Claude Code.
-
-## 📄 License
+## License
 
 MIT © Omkar Kovvali
-
-See [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-- Built with [Model Context Protocol](https://modelcontextprotocol.io/)
-- Uses [GitHub Gist API](https://docs.github.com/en/rest/gists)
-- Powered by [Claude Code](https://www.anthropic.com/claude)
-
-## 📞 Support
-
-- **Issues**: [GitHub Issues](https://github.com/OmkarKovvali/claude-session-share/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/OmkarKovvali/claude-session-share/discussions)
-- **Email**: okovvali5@gmail.com
-
----
-
-**Made with ❤️ for the Claude Code community**

package/dist/__tests__/e2e.test.js

@@ -162,10 +162,12 @@ describe('End-to-End Session Sharing Workflow', () => {
             for (const msg of assistantMsgs) {
                 expect(msg.snapshot.thinking).toBeNull();
             }
-            // Verify: Paths sanitized (absolute → relative)
+            // Verify: Original paths sanitized, then restored to import project path
+            // - Original path (/Users/test/myproject) is NOT preserved
+            // - cwd is restored to the import directory (absolute path)
             const userMsg = importedMessages[0];
             expect(userMsg.cwd).not.toContain('/Users/test/');
-            expect(userMsg.cwd).toMatch(/^(myproject|\.)/); // Should be relative
+            expect(userMsg.cwd).toBe(importDir); // Restored to import project path
             const firstAssistant = importedMessages[1];
             const toolResultContent = firstAssistant.snapshot.messages[1].content;
             expect(toolResultContent).not.toContain('/Users/test/myproject/');

package/dist/__tests__/path-encoding.test.js

@@ -2,6 +2,9 @@
  * Tests for path encoding utilities
  *
  * Validates Claude Code's path encoding scheme for session directories.
+ * Claude Code encoding:
+ * 1. Replaces `/` with `-` (keeping leading dash from root /)
+ * 2. Replaces `_` with `-` (normalizes underscores to hyphens)
  */
 import { describe, it, expect } from 'vitest';
 import { encodeProjectPath, decodeProjectPath, getSessionDirectory } from '../utils/path-encoding.js';
@@ -9,68 +12,87 @@ import { homedir } from 'os';
 import { join } from 'path';
 describe('path-encoding', () => {
     describe('encodeProjectPath', () => {
-        it('encodes absolute Unix path correctly', () => {
+        it('encodes absolute Unix path correctly (keeps leading dash)', () => {
             const result = encodeProjectPath('/Users/name/project');
-            expect(result).toBe('Users-name-project');
+            expect(result).toBe('-Users-name-project');
         });
         it('encodes path with multiple segments', () => {
             const result = encodeProjectPath('/Users/name/my-project/subdir');
-            expect(result).toBe('Users-name-my-project-subdir');
+            expect(result).toBe('-Users-name-my-project-subdir');
         });
         it('handles path with existing dashes', () => {
             const result = encodeProjectPath('/Users/name/my-awesome-project');
-            expect(result).toBe('Users-name-my-awesome-project');
+            expect(result).toBe('-Users-name-my-awesome-project');
         });
         it('handles single segment path', () => {
             const result = encodeProjectPath('/project');
-            expect(result).toBe('project');
+            expect(result).toBe('-project');
         });
         it('handles path with multiple consecutive slashes', () => {
             const result = encodeProjectPath('/Users//name///project');
-            expect(result).toBe('Users--name---project');
+            expect(result).toBe('-Users--name---project');
         });
         it('handles path with trailing slash', () => {
             const result = encodeProjectPath('/Users/name/project/');
-            expect(result).toBe('Users-name-project-');
+            expect(result).toBe('-Users-name-project-');
+        });
+        it('converts underscores to hyphens', () => {
+            const result = encodeProjectPath('/Users/name/my_project');
+            expect(result).toBe('-Users-name-my-project');
+        });
+        it('handles path with both underscores and dashes', () => {
+            const result = encodeProjectPath('/Users/name/my_cool-project');
+            expect(result).toBe('-Users-name-my-cool-project');
         });
     });
     describe('decodeProjectPath', () => {
-        it('decodes encoded path correctly', () => {
-            const result = decodeProjectPath('Users-name-project');
+        it('decodes encoded path correctly (leading dash becomes /)', () => {
+            const result = decodeProjectPath('-Users-name-project');
             expect(result).toBe('/Users/name/project');
         });
         it('decodes path with multiple segments', () => {
-            const result = decodeProjectPath('Users-name-myproject-subdir');
+            const result = decodeProjectPath('-Users-name-myproject-subdir');
             expect(result).toBe('/Users/name/myproject/subdir');
         });
-        it('is inverse of encodeProjectPath', () => {
+        it('is inverse of encodeProjectPath for paths without underscores', () => {
             const original = '/Users/name/project';
             const encoded = encodeProjectPath(original);
             const decoded = decodeProjectPath(encoded);
             expect(decoded).toBe(original);
         });
         it('handles single segment', () => {
-            const result = decodeProjectPath('project');
+            const result = decodeProjectPath('-project');
             expect(result).toBe('/project');
         });
+        it('handles paths without leading dash (legacy format)', () => {
+            // Legacy format without leading dash
+            const result = decodeProjectPath('Users-name-project');
+            expect(result).toBe('Users/name/project');
+        });
     });
     describe('getSessionDirectory', () => {
         it('constructs correct session directory path', () => {
             const projectPath = '/Users/name/project';
             const result = getSessionDirectory(projectPath);
-            const expected = join(homedir(), '.claude', 'projects', 'Users-name-project');
+            const expected = join(homedir(), '.claude', 'projects', '-Users-name-project');
             expect(result).toBe(expected);
         });
         it('handles complex project paths', () => {
             const projectPath = '/Users/name/my-awesome-project/subdir';
             const result = getSessionDirectory(projectPath);
-            const expected = join(homedir(), '.claude', 'projects', 'Users-name-my-awesome-project-subdir');
+            const expected = join(homedir(), '.claude', 'projects', '-Users-name-my-awesome-project-subdir');
             expect(result).toBe(expected);
         });
         it('handles project path with existing dashes', () => {
             const projectPath = '/opt/code/my-app';
             const result = getSessionDirectory(projectPath);
-            const expected = join(homedir(), '.claude', 'projects', 'opt-code-my-app');
+            const expected = join(homedir(), '.claude', 'projects', '-opt-code-my-app');
+            expect(result).toBe(expected);
+        });
+        it('handles project path with underscores', () => {
+            const projectPath = '/Users/name/cc_links';
+            const result = getSessionDirectory(projectPath);
+            const expected = join(homedir(), '.claude', 'projects', '-Users-name-cc-links');
             expect(result).toBe(expected);
         });
     });

package/dist/__tests__/prompts.test.js

@@ -0,0 +1,147 @@
+/**
+ * MCP Prompt Integration Tests
+ *
+ * Tests slash command functionality via MCP prompts.
+ * Prompts convert slash commands to natural language that triggers tool handlers.
+ */
+import { describe, it, expect } from 'vitest';
+describe('MCP Prompts', () => {
+    // Test prompt definitions (schema)
+    const promptDefinitions = {
+        prompts: [
+            {
+                name: 'share',
+                description: 'Share current Claude Code session to GitHub Gist',
+                arguments: [
+                    {
+                        name: 'session_path',
+                        description: 'Optional: Path to session file (defaults to most recent)',
+                        required: false,
+                    },
+                ],
+            },
+            {
+                name: 'import',
+                description: 'Import shared session from GitHub Gist URL',
+                arguments: [
+                    {
+                        name: 'gist_url',
+                        description: 'GitHub Gist URL (e.g., https://gist.github.com/user/abc123)',
+                        required: true,
+                    },
+                    {
+                        name: 'project_path',
+                        description: 'Optional: Local project directory (defaults to current directory)',
+                        required: false,
+                    },
+                ],
+            },
+        ],
+    };
+    // Test GetPrompt handler logic
+    const handleGetPrompt = (name, args) => {
+        if (name === 'share') {
+            const sessionPath = args?.session_path;
+            return {
+                description: 'Share session to GitHub Gist',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: sessionPath
+                                ? `Share my session from ${sessionPath} to GitHub Gist`
+                                : 'Share my current session to GitHub Gist',
+                        },
+                    },
+                ],
+            };
+        }
+        if (name === 'import') {
+            const gistUrl = args?.gist_url;
+            const projectPath = args?.project_path;
+            if (!gistUrl) {
+                throw new Error('gist_url argument is required');
+            }
+            return {
+                description: 'Import session from Gist',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: projectPath
+                                ? `Import session from ${gistUrl} to ${projectPath}`
+                                : `Import session from ${gistUrl}`,
+                        },
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    };
+    describe('ListPrompts', () => {
+        it('should list share and import prompts', () => {
+            expect(promptDefinitions.prompts).toHaveLength(2);
+            expect(promptDefinitions.prompts[0].name).toBe('share');
+            expect(promptDefinitions.prompts[1].name).toBe('import');
+        });
+        it('should include descriptions for both prompts', () => {
+            expect(promptDefinitions.prompts[0].description).toContain('Share current Claude Code session');
+            expect(promptDefinitions.prompts[1].description).toContain('Import shared session');
+        });
+        it('should define correct arguments for share prompt', () => {
+            const sharePrompt = promptDefinitions.prompts.find((p) => p.name === 'share');
+            expect(sharePrompt?.arguments).toHaveLength(1);
+            expect(sharePrompt?.arguments?.[0].name).toBe('session_path');
+            expect(sharePrompt?.arguments?.[0].required).toBe(false);
+        });
+        it('should define correct arguments for import prompt', () => {
+            const importPrompt = promptDefinitions.prompts.find((p) => p.name === 'import');
+            expect(importPrompt?.arguments).toHaveLength(2);
+            expect(importPrompt?.arguments?.[0].name).toBe('gist_url');
+            expect(importPrompt?.arguments?.[0].required).toBe(true);
+            expect(importPrompt?.arguments?.[1].name).toBe('project_path');
+            expect(importPrompt?.arguments?.[1].required).toBe(false);
+        });
+    });
+    describe('GetPrompt - share', () => {
+        it('should return share prompt without arguments', () => {
+            const response = handleGetPrompt('share', {});
+            expect(response.description).toBe('Share session to GitHub Gist');
+            expect(response.messages).toHaveLength(1);
+            expect(response.messages[0].role).toBe('user');
+            expect(response.messages[0].content.type).toBe('text');
+            expect(response.messages[0].content.text).toBe('Share my current session to GitHub Gist');
+        });
+        it('should return share prompt with session_path argument', () => {
+            const response = handleGetPrompt('share', { session_path: '/path/to/session.jsonl' });
+            expect(response.messages[0].content.text).toBe('Share my session from /path/to/session.jsonl to GitHub Gist');
+        });
+    });
+    describe('GetPrompt - import', () => {
+        it('should return import prompt with gist_url only', () => {
+            const response = handleGetPrompt('import', { gist_url: 'https://gist.github.com/user/abc123' });
+            expect(response.description).toBe('Import session from Gist');
+            expect(response.messages).toHaveLength(1);
+            expect(response.messages[0].role).toBe('user');
+            expect(response.messages[0].content.type).toBe('text');
+            expect(response.messages[0].content.text).toBe('Import session from https://gist.github.com/user/abc123');
+        });
+        it('should return import prompt with both gist_url and project_path', () => {
+            const response = handleGetPrompt('import', {
+                gist_url: 'https://gist.github.com/user/abc123',
+                project_path: '/my/project',
+            });
+            expect(response.messages[0].content.text).toBe('Import session from https://gist.github.com/user/abc123 to /my/project');
+        });
+        it('should error when import prompt missing gist_url', () => {
+            expect(() => handleGetPrompt('import', {})).toThrow('gist_url argument is required');
+        });
+    });
+    describe('GetPrompt - error cases', () => {
+        it('should error on unknown prompt name', () => {
+            expect(() => handleGetPrompt('unknown', {})).toThrow('Unknown prompt: unknown');
+        });
+    });
+});