ccmv 1.0.0

package/CLAUDE.md

@@ -0,0 +1,159 @@
+# ccmv - Project Guidelines
+
+## Overview
+
+`ccmv` is a Node.js CLI tool that migrates project directories, updating all Claude Code and/or Cursor references when a project is moved to a new location.
+
+**Supported configurations:**
+- Claude Code + Cursor (both)
+- Claude Code only
+- Cursor only
+
+## Project Structure
+
+```
+ccmv/
+├── package.json      # npm package config with bin entry
+├── bin/
+│   └── ccmv.js       # CLI entry point
+├── lib/
+│   ├── index.js      # Main orchestration logic
+│   ├── logger.js     # Colored console output
+│   ├── utils.js      # Path encoding, file URIs, hashing
+│   ├── claude.js     # Claude Code operations
+│   └── cursor.js     # Cursor editor operations
+├── README.md         # User documentation
+└── CLAUDE.md         # This file
+```
+
+## Technical Details
+
+### Claude Code Data Locations
+
+- `~/.claude/projects/{encoded-path}/` - Project-specific session data
+- `~/.claude/history.jsonl` - Global history file
+- Path encoding: `/`, `:`, spaces → `-`
+
+### Cursor Data Locations
+
+```
+~/Library/Application Support/Cursor/User/
+├── globalStorage/
+│   ├── storage.json          # profileAssociations.workspaces (path list)
+│   └── state.vscdb           # SQLite ItemTable: history.recentlyOpenedPathsList, repositoryTracker.paths
+└── workspaceStorage/
+    └── {hash}/
+        ├── workspace.json    # {"folder": "file://..."} or {"workspace": "file://..."}
+        └── state.vscdb       # Workspace-specific SQLite (ItemTable + cursorDiskKV)
+```
+
+- **Path format**: `file:///Users/foo/my%20project` (URL encoded)
+- **SQLite update**: Uses `better-sqlite3` for database operations
+
+### Cursor Workspace Hash (Critical)
+
+Cursor/VSCode uses MD5 hash of `path + birthtime_ms` for workspaceStorage directory names:
+
+```javascript
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+
+const stat = statSync(path);
+const hash = createHash('md5')
+    .update(path)
+    .update(String(stat.birthtime.getTime()))
+    .digest('hex');
+```
+
+**Key Points:**
+- Uses Node.js native `fs.statSync().birthtime.getTime()` for consistent millisecond precision
+- `mv` command preserves birthtime on same volume, so new path hash is predictable
+- When project moves, ccmv renames workspace directory to match new hash
+- Chat history is stored in `workspaceStorage/{hash}/state.vscdb` (cursorDiskKV table)
+
+**Duplicate Workspace Handling:**
+- Multiple workspace directories can point to the same path (from failed migrations or Cursor quirks)
+- `mergeDuplicateWorkspaces()` finds all workspaces pointing to new path
+- Keeps the workspace with the **larger** `state.vscdb` (contains more chat history)
+
+### Key Modules
+
+| Module | Purpose |
+|--------|---------|
+| `lib/index.js` | CLI parsing, orchestration, rollback handling |
+| `lib/logger.js` | Colored log output functions |
+| `lib/utils.js` | `encodePath`, `pathToFileUri`, `getWorkspaceHash`, `resolvePath` |
+| `lib/claude.js` | Backup, rename, update, verify Claude data |
+| `lib/cursor.js` | Detect, backup, update Cursor storage.json and SQLite DBs |
+
+### Error Handling
+
+- Validates all paths before making changes
+- Requires at least one of Claude Code or Cursor data (fails if neither exists)
+- Creates backups before any modifications
+- Auto-rollback on any error during migration
+- Cursor must not be running (checked before migration)
+
+## Development
+
+### Setup
+
+```bash
+npm install
+```
+
+### Testing
+
+```bash
+# Create test project
+mkdir -p /tmp/test-proj-a
+mkdir -p ~/.claude/projects/-tmp-test-proj-a
+echo '{"cwd":"/tmp/test-proj-a"}' > ~/.claude/projects/-tmp-test-proj-a/test.jsonl
+
+# Test dry-run
+node bin/ccmv.js --dry-run /tmp/test-proj-a /tmp/test-proj-b
+
+# Test with npx (from package directory)
+npx . --dry-run /tmp/test-proj-a /tmp/test-proj-b
+
+# Cleanup
+rm -rf /tmp/test-proj-* ~/.claude/projects/-tmp-test-proj-*
+```
+
+### Local Development
+
+```bash
+# Run directly
+node bin/ccmv.js --help
+
+# Or link globally for testing
+npm link
+ccmv --help
+```
+
+### Known Issues
+
+- Cursor must be closed during migration (enforced by `checkCursorNotRunning`)
+- **Cross-volume moves**: `mv` to different volume may not preserve birthtime, potentially breaking hash prediction (untested)
+- On Linux, Cursor data is at `~/.config/Cursor/User/` instead of `~/Library/Application Support/`
+
+### Troubleshooting Cursor Chat History Loss
+
+If chat history is lost after migration:
+
+1. **Check workspace directories**: Look at `~/Library/Application Support/Cursor/User/workspaceStorage/*/workspace.json` for entries pointing to your path
+2. **Compare state.vscdb sizes**: Larger file usually has more chat data
+3. **Calculate expected hash**:
+   ```javascript
+   import { createHash } from 'node:crypto';
+   import { statSync } from 'node:fs';
+
+   const path = '/your/project/path';
+   const stat = statSync(path);
+   const hash = createHash('md5')
+       .update(path)
+       .update(String(stat.birthtime.getTime()))
+       .digest('hex');
+   console.log(hash);
+   ```
+4. **Check cursorDiskKV table**: Chat data is in `state.vscdb` under key `composer.composerData`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saqoosha
+
+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,114 @@
+# ccmv
+
+Claude Code project directory migration tool.
+
+## Problem
+
+When you move a project directory, Claude Code loses track of your conversation history because it's stored in `~/.claude/projects/` using path-encoded directory names.
+
+## Solution
+
+`ccmv` moves your project and updates all Claude Code and/or Cursor references automatically. Works with:
+- Projects with both Claude Code and Cursor data
+- Claude Code-only projects (no Cursor)
+- Cursor-only projects (no Claude Code history)
+
+## Installation
+
+```bash
+# Using npm (recommended)
+npm install -g ccmv
+
+# Or using npx (no installation required)
+npx ccmv --help
+```
+
+## Usage
+
+```
+ccmv [OPTIONS] <old-path> <new-path>
+
+Options:
+  --refs-only    Only update references (don't move directory)
+  --dry-run      Preview changes without executing
+  --keep-backup  Keep backup after successful migration
+  --no-cursor    Skip Cursor editor data updates
+  --quiet        Suppress detailed output
+  --help         Show help
+```
+
+## Examples
+
+```bash
+# Move project to new location
+ccmv ~/projects/myapp ~/work/myapp
+
+# Or using npx
+npx ccmv ~/projects/myapp ~/work/myapp
+
+# Preview what would happen
+ccmv --dry-run ~/old-project ~/new-project
+
+# Already moved? Just update refs
+ccmv --refs-only /old/path /new/path
+```
+
+## What It Does
+
+1. Detects Claude Code and/or Cursor data for the project
+2. Creates backup of existing data
+3. Moves project directory (unless `--refs-only`)
+4. Updates Claude Code data (if exists):
+   - Renames `~/.claude/projects/{encoded-path}/`
+   - Updates `cwd` field in all JSONL files
+   - Updates `~/.claude/history.jsonl`
+5. Updates Cursor workspace data (if exists):
+   - Renames `workspaceStorage/{hash}/` directory
+   - Updates `storage.json` (profile associations)
+   - Updates `state.vscdb` (global SQLite database)
+   - Updates `workspaceStorage/*/workspace.json`
+   - Updates `workspaceStorage/*/state.vscdb`
+6. Verifies migration success
+7. Auto-rollback on any failure
+
+**Note:** Migration requires at least one of Claude Code or Cursor data to exist. If neither exists, use regular `mv` command.
+
+## How Claude Code Stores Data
+
+```
+~/.claude/
+├── projects/
+│   └── -Users-jane-myproject/    # Encoded from /Users/jane/myproject
+│       ├── session-abc.jsonl     # Contains "cwd":"/Users/jane/myproject"
+│       └── subagents/
+│           └── agent-xyz.jsonl
+└── history.jsonl                  # Global history with cwd fields
+```
+
+Path encoding: `/Users/jane/foo bar` → `-Users-jane-foo-bar`
+
+## Cursor Data (Auto-detected)
+
+If Cursor is installed, `ccmv` also updates:
+
+```
+~/Library/Application Support/Cursor/User/
+├── globalStorage/
+│   ├── storage.json          # Profile workspace associations
+│   └── state.vscdb           # SQLite: history, repository paths
+└── workspaceStorage/
+    └── {hash}/
+        ├── workspace.json    # Workspace folder URI
+        └── state.vscdb       # Workspace-specific data
+```
+
+**Note:** Cursor must be closed during migration to prevent data corruption.
+
+## Requirements
+
+- Node.js 18.0.0 or later
+- macOS or Linux
+
+## License
+
+MIT

package/bin/ccmv.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from '../lib/index.js';
+
+main(process.argv.slice(2));