claude-session-share 1.0.0 → 1.1.0

package/README.md

@@ -1,21 +1,21 @@
 # claude-session-share
 
-> **MCP server for sharing Claude Code sessions via GitHub Gist with automatic privacy protection**
+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.
+Share your Claude Code conversations while keeping private data safe. Export sessions to shareable GitHub Gist links and import them back—all through natural language or CLI.
 
 [![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 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
 
-## 📦 Installation
+## Installation
 
 ### Prerequisites
 
@@ -37,11 +37,11 @@ npm install -g claude-session-share
 4. Check the **`gist`** scope
 5. Generate and copy the token
 
-## ⚙️ Configuration
+## Configuration
 
-Add the MCP server to your Claude Code configuration:
+Add the MCP server to your Claude Code configuration.
 
-### Option 1: User Config (Recommended)
+### User Config (Recommended)
 
 Create or edit `~/.claude/mcp.json`:
 
@@ -59,24 +59,23 @@ Create or edit `~/.claude/mcp.json`:
 }
 ```
 
-### Option 2: Project-Specific Config
+### 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
 # You should see "claude-session-share" in the list
 ```
 
-## 🚀 Usage
+## Usage
 
-### Sharing a Session
+### Natural Language (via MCP)
 
-In any Claude Code conversation, simply say:
+In any Claude Code conversation:
 
 ```
 "Share my current session to GitHub Gist"
@@ -88,28 +87,33 @@ Claude will:
 3. Upload to a secret (unlisted) GitHub Gist
 4. Return a shareable link
 
-**Example output:**
-```
-✓ Session shared successfully!
-Link: https://gist.github.com/username/abc123...
+To import a shared session:
 
-Share this link with anyone. They can import it with:
-"Import session from https://gist.github.com/username/abc123..."
+```
+"Import this session: https://gist.github.com/username/abc123..."
 ```
 
-### Importing a Session
+### Command Line (Standalone CLI)
 
-To import a shared session:
+#### Share a session
 
-```
-"Import this session: https://gist.github.com/username/abc123..."
+```bash
+# Share most recent session
+npx claude-session-share share
+
+# Share specific session file
+npx claude-session-share share --session-path ~/.claude/projects/abc/session.jsonl
 ```
 
-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
+#### Import a session
+
+```bash
+# Import to current directory
+npx claude-session-share import https://gist.github.com/user/abc123
+
+# Import to specific directory
+npx claude-session-share import abc123 --project-path /Users/name/project
+```
 
 ### Resuming an Imported Session
 
@@ -119,13 +123,17 @@ 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 resume directly with the session ID:
+
+```bash
+claude --resume <session-id>
+```
 
-## 🔐 Privacy Protection
+## Privacy Protection
 
 Every shared session is automatically sanitized:
 
-### ✅ What Gets Removed/Sanitized
+### What Gets Removed/Sanitized
 
 - **Thinking Blocks** - Internal reasoning stripped completely
 - **Absolute Paths** - `/Users/you/project/file.ts` → `file.ts`
@@ -133,7 +141,7 @@ Every shared session is automatically sanitized:
 - **Tokens** - Bearer tokens, OAuth tokens → `[REDACTED]`
 - **Secrets** - Environment variables, passwords (key=value format) → `[REDACTED]`
 
-### ✅ What Gets Preserved
+### What Gets Preserved
 
 - Conversation flow and context
 - Code examples and explanations
@@ -145,11 +153,8 @@ Every shared session is automatically sanitized:
 
 - 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 Reference
 
 ### `share_session`
 
@@ -167,17 +172,17 @@ Exports the current session to GitHub Gist.
 Imports a session from a GitHub Gist.
 
 **Parameters:**
-- `gistUrl` - GitHub Gist URL (e.g., `https://gist.github.com/user/abc123`)
-- `projectPath` (optional) - Local project directory (defaults to current directory)
+- `gistUrl` - GitHub Gist URL or bare gist ID
+- `projectPath` - Local project directory for import
 
 **Returns:**
 - `sessionPath` - Path to imported session file
 - `sessionId` - New session ID
 - `messageCount` - Number of messages imported
 
-## 🛠️ Development
+## Development
 
-### Clone and Setup
+### Setup
 
 ```bash
 git clone https://github.com/OmkarKovvali/claude-session-share.git
@@ -195,7 +200,7 @@ npm run build
 
 ```bash
 npm test
-# 337 tests with full coverage
+# 420 tests
 ```
 
 ### Project Structure
@@ -204,64 +209,21 @@ npm test
 claude-session-share/
 ├── src/
 │   ├── index.ts                 # MCP server entry point
+│   ├── cli.ts                   # CLI entry point
 │   ├── gist/                    # GitHub Gist integration
 │   ├── sanitization/            # Privacy protection
 │   ├── services/                # Share/import orchestration
 │   ├── session/                 # Session read/write
-│   └── utils/                   # UUID remapping, etc.
+│   └── utils/                   # UUID remapping, path encoding
 ├── 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
+## Troubleshooting
 
 ### "Not authenticated" Error
 
-Make sure your `GITHUB_TOKEN` is set in the MCP configuration:
+Ensure `GITHUB_TOKEN` is set in MCP configuration:
 ```json
 "env": {
   "GITHUB_TOKEN": "ghp_your_token_here"
@@ -274,12 +236,7 @@ Ensure you're in a directory with an active Claude Code session. Sessions are st
 
 ### 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.
+After importing, restart Claude Code to refresh the session list. The session file should be in `~/.claude/projects/-{encoded-path}/`.
 
 ### MCP Server Not Listed
 
@@ -287,27 +244,21 @@ Verify your MCP configuration:
 ```bash
 cat ~/.claude/mcp.json
 ```
-
 Then restart Claude Code.
 
-## 📄 License
+## Contributing
 
-MIT © Omkar Kovvali
-
-See [LICENSE](LICENSE) file for details.
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes
+4. Push to the branch
+5. Open a Pull Request
 
-## 🙏 Acknowledgments
+## License
 
-- 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)
+MIT © Omkar Kovvali
 
-## 📞 Support
+## 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__/cli.test.js

@@ -0,0 +1,120 @@
+/**
+ * Tests for CLI entry point
+ *
+ * Validates command parsing and integration with services
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { uploadSession } from '../services/session-uploader.js';
+import { importSession } from '../services/session-importer.js';
+// Mock the services at module level
+vi.mock('../services/session-uploader.js', () => ({
+    uploadSession: vi.fn(),
+}));
+vi.mock('../services/session-importer.js', () => ({
+    importSession: vi.fn(),
+}));
+// Mock fs/promises for findMostRecentSession
+vi.mock('fs/promises', async () => {
+    const actual = await vi.importActual('fs/promises');
+    return {
+        ...actual,
+        readdir: vi.fn(),
+        stat: vi.fn(),
+    };
+});
+describe('CLI argument parsing', () => {
+    it('should parse share command with session path', () => {
+        // Test that share command with --session-path flag works
+        const args = ['share', '--session-path', '/path/to/session.jsonl'];
+        // Find the session-path value
+        const pathIndex = args.indexOf('--session-path');
+        const sessionPath = pathIndex !== -1 && pathIndex + 1 < args.length
+            ? args[pathIndex + 1]
+            : null;
+        expect(sessionPath).toBe('/path/to/session.jsonl');
+    });
+    it('should parse share command without session path', () => {
+        const args = ['share'];
+        const pathIndex = args.indexOf('--session-path');
+        const sessionPath = pathIndex !== -1 && pathIndex + 1 < args.length
+            ? args[pathIndex + 1]
+            : null;
+        expect(sessionPath).toBeNull();
+    });
+    it('should parse import command with gist URL and default project path', () => {
+        // Simulate: node cli.js import https://gist...
+        // After "import" is consumed, remaining args are:
+        const argsAfterCommand = ['https://gist.github.com/user/abc123'];
+        const gistUrl = argsAfterCommand[0];
+        const pathIndex = argsAfterCommand.indexOf('--project-path');
+        const projectPath = pathIndex !== -1 && pathIndex + 1 < argsAfterCommand.length
+            ? argsAfterCommand[pathIndex + 1]
+            : process.cwd();
+        expect(gistUrl).toBe('https://gist.github.com/user/abc123');
+        expect(projectPath).toBe(process.cwd());
+    });
+    it('should parse import command with project-path flag', () => {
+        // Simulate: node cli.js import abc123 --project-path /tmp/test
+        const argsAfterCommand = ['abc123', '--project-path', '/tmp/test'];
+        const gistUrl = argsAfterCommand[0];
+        const pathIndex = argsAfterCommand.indexOf('--project-path');
+        const projectPath = pathIndex !== -1 && pathIndex + 1 < argsAfterCommand.length
+            ? argsAfterCommand[pathIndex + 1]
+            : process.cwd();
+        expect(gistUrl).toBe('abc123');
+        expect(projectPath).toBe('/tmp/test');
+    });
+    it('should handle missing gist URL in import command', () => {
+        // Simulate: node cli.js import (no URL provided)
+        const argsAfterCommand = [];
+        const gistUrl = argsAfterCommand[0];
+        expect(gistUrl).toBeUndefined();
+    });
+});
+describe('CLI service integration', () => {
+    it('uploadSession service should be importable', () => {
+        expect(uploadSession).toBeDefined();
+        expect(typeof uploadSession).toBe('function');
+    });
+    it('importSession service should be importable', () => {
+        expect(importSession).toBeDefined();
+        expect(typeof importSession).toBe('function');
+    });
+    it('uploadSession mock can be configured', () => {
+        vi.mocked(uploadSession).mockResolvedValue('https://gist.github.com/test/123');
+        expect(vi.mocked(uploadSession)).toBeDefined();
+    });
+    it('importSession mock can be configured', () => {
+        vi.mocked(importSession).mockResolvedValue({
+            sessionPath: '/path/to/session.jsonl',
+            sessionId: 'test-id',
+            messageCount: 10,
+            projectPath: '/test',
+        });
+        expect(vi.mocked(importSession)).toBeDefined();
+    });
+});
+describe('CLI usage validation', () => {
+    it('should have share and import as valid commands', () => {
+        const validCommands = ['share', 'import'];
+        expect(validCommands).toContain('share');
+        expect(validCommands).toContain('import');
+        expect(validCommands).not.toContain('unknown');
+    });
+    it('should validate share command structure', () => {
+        // share command can have optional --session-path
+        const shareArgs1 = ['share'];
+        const shareArgs2 = ['share', '--session-path', '/path'];
+        expect(shareArgs1[0]).toBe('share');
+        expect(shareArgs2[0]).toBe('share');
+        expect(shareArgs2.includes('--session-path')).toBe(true);
+    });
+    it('should validate import command structure', () => {
+        // import command requires gist URL, optional --project-path
+        const importArgsAfterCommand1 = ['https://gist.github.com/user/id'];
+        const importArgsAfterCommand2 = ['abc123', '--project-path', '/path'];
+        expect(importArgsAfterCommand1[0]).toBe('https://gist.github.com/user/id');
+        expect(importArgsAfterCommand2[0]).toBe('abc123');
+        expect(importArgsAfterCommand2.includes('--project-path')).toBe(true);
+    });
+});

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);
         });
     });