Update session listing and workspace handling

Changes:
- Enhanced `listSessions()` to clarify deduplication behavior when filtering by workspace, ensuring no cross-workspace deduplication occurs when the `--workspace` option is set.
- Updated documentation in `CLAUDE.md` to reflect changes in session deduplication and workspace path resolution.
- Improved error handling in `workspaceUriToPath()` to decode percent-encoded characters in workspace URIs.
- Incremented version in `package.json` to 0.12.1.

Why: These updates improve user clarity on session listing behavior and enhance workspace path handling, ensuring a more robust experience.

Author: Dangerdan9631

CLAUDE.md

@@ -114,11 +114,11 @@ So when someone uses `import { listSessions } from 'cursor-history'`, they're ca
 
 ### Storage Layer (`src/core/storage.ts`)
 
-- `listSessions()` - Uses workspace storage for listing (correct paths); when listing all (no workspace filter), deduplicates by session ID and attributes to first workspace in deterministic order (.code-workspace paths before folder paths)
+- `listSessions()` - Uses workspace storage for listing (correct paths); when listing all sessions (no `--workspace` filter), deduplicates by session ID and attributes to first workspace in deterministic order (.code-workspace paths before folder paths)
 - `getSession(identifier, ...)` - Get session by 1-based index (number) or composer ID (string). Tries global storage first (full AI responses), falls back to workspace. Returns null when index or composer ID not found.
 - `findWorkspaceForSession(sessionId)` - Finds which workspace contains a session by ID
 - `findWorkspaceByPath(path)` - Finds workspace by its project path (folder or .code-workspace file path)
-- `readWorkspaceJson(workspaceDir)` - Reads workspace path from `workspace.json`: supports `folder` (single-folder workspace, file URI) and `configuration` (.code-workspace file URI); prefers `folder` when both exist; same logic used when reading from backup zip
+- `readWorkspaceJson(workspaceDir)` - Reads workspace path from `workspace.json`: supports `folder` (single-folder workspace, file URI) and `workspace` (.code-workspace file URI); prefers `workspace` when both exist; same logic used when reading from backup zip
 - `getComposerData(db)` - Reads composer array, handles both `allComposers` and legacy formats
 - `updateComposerData(db, composers)` - Writes composer array, preserves original format
 - `resolveSessionIdentifiers(input)` - Converts index/ID/comma-separated to session ID array
@@ -372,7 +372,7 @@ Edit `extractBubbleText()` in `src/core/storage.ts`. Priority matters:
 - Workspace file path resolution: Workspaces opened via a .code-workspace file are now discovered and matchable
   - `readWorkspaceJson()` and `readWorkspaceJsonFromBackup()` now support the `workspace` key (workspace file URI) in addition to `folder` (single-folder URI); prefer `workspace` when both exist;
   - Listing, `--workspace` filter, and `findWorkspaceByPath()` work when the workspace path is the .code-workspace file path
-  - Session deduplication: When Cursor has two workspaceStorage entries (folder and .code-workspace), both may receive the same chats. When listing all sessions (no `--workspace` filter), the tool deduplicates by session ID so each chat appears once. Attribution is deterministic: workspaces are sorted by path with .code-workspace paths before others, so the session is attributed to the .code-workspace workspace when the same session exists in both. Filtering or exporting by `--workspace` is unchanged (only that workspace's DB is read).
+  - Session deduplication: When Cursor has two workspaceStorage entries (folder and .code-workspace), both may receive the same chats. When listing all sessions (no `--workspace` filter), the tool deduplicates by session ID so each chat appears once. Attribution is deterministic: workspaces are sorted by path with .code-workspace paths before others, so the session is attributed to the .code-workspace workspace when the same session exists in both. Deduplication is not applied when `--workspace` is used; each workspace's DB is listed as-is. Filtering or exporting by `--workspace` is unchanged (only that workspace's DB is read).
 - 010-fix-timestamp-fallback: Fixed incorrect timestamps on pre-2025-09 sessions (Issue #13)
   - Extended `RawBubbleData.timingInfo` with `clientRpcSendTime` and `clientSettleTime` fields
   - New `extractTimestamp()` function in `src/core/storage.ts`: priority chain `createdAt` > `clientRpcSendTime` > `clientSettleTime` > `clientEndTime` > `null`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-history",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "The ultimate CLI tool and library to browse, search, export, migrate, and backup your Cursor AI chat history",
   "type": "module",
   "main": "dist/lib/index.js",

src/cli/formatters/table.ts

@@ -123,7 +123,11 @@ export function formatSessionsTable(sessions: ChatSessionSummary[], showIds = fa
   }
 
   lines.push('');
-  lines.push(pc.dim(`Showing ${sessions.length} session(s). Use "show <#>" or "show <composer-id>" to view details.`));
+  lines.push(
+    pc.dim(
+      `Showing ${sessions.length} session(s). Use "show <#>" or "show <composer-id>" to view details.`
+    )
+  );
   if (showIds) {
     lines.push(pc.dim(`Composer IDs can be used with external tools and show/export commands.`));
   }

src/cli/index.ts

@@ -25,7 +25,10 @@ program
   .version(packageJson.version, '-v, --version', 'Show version number')
   .option('--json', 'Output in JSON format')
   .option('--data-path <path>', 'Custom Cursor data directory')
-  .option('-w, --workspace <path>', 'Filter by workspace path');
+  .option(
+    '-w, --workspace <path>',
+    'Filter by workspace path (no session deduplication across workspaces when set)'
+  );
 
 // Lazy-load commands to avoid circular dependencies
 async function loadCommands() {

src/core/storage.ts

@@ -87,23 +87,27 @@ export async function openDatabaseReadWrite(dbPath: string): Promise<Database> {
 // ============================================================================
 
 /**
- * Workspace.json shape: folder (single-folder) or workspace (.code-workspace path) 
+ * Workspace.json shape: folder (single-folder) or workspace (.code-workspace path)
  */
 interface WorkspaceJsonShape {
   folder?: string;
   workspace?: string;
 }
 
 /**
- * Convert file:// URI from workspace.json to filesystem path 
+ * Convert file:// URI from workspace.json to filesystem path
  */
 function workspaceUriToPath(uri: string): string {
-  return uri.replace(/^file:\/\//, '').replace(/%20/g, ' ');
+  try {
+    return decodeURIComponent(uri.replace(/^file:\/\//, ''));
+  } catch {
+    return uri.replace(/^file:\/\//, '');
+  }
 }
 
 /**
  * Read workspace path from parsed workspace.json (folder or configuration).
- * Prefers folder; falls back to configuration for .code-workspace workspaces.
+ * Prefers workspace (.code-workspace path); falls back to folder for single-folder workspaces.
  */
 function getWorkspacePathFromJson(data: WorkspaceJsonShape): string | null {
   if (data.workspace) {
@@ -341,6 +345,8 @@ function getChatDataFromDb(db: Database): { data: string; bundle: CursorChatBund
 /**
  * List chat sessions with optional filtering
  * Uses workspace storage for listing (has correct paths and complete list)
+ * When `options.workspacePath` is unset, deduplicates by session ID across workspaces (deterministic order).
+ * When `workspacePath` is set, lists that workspace's DB only with no cross-workspace deduplication.
  * @param options - List options (limit, all, workspacePath)
  * @param customDataPath - Custom Cursor data path (for live data)
  * @param backupPath - Path to backup zip file (if reading from backup)
@@ -355,11 +361,12 @@ export async function listSessions(
 
   // Filter by workspace if specified
   // Deterministic order: .code-workspace paths before others, then by path (for stable attribution when deduping)
-  const filteredWorkspaces = (options.workspacePath
-    ? workspaces.filter(
-        (w) => w.path === options.workspacePath || w.path.endsWith(options.workspacePath ?? '')
-      )
-    : workspaces
+  const filteredWorkspaces = (
+    options.workspacePath
+      ? workspaces.filter(
+          (w) => w.path === options.workspacePath || w.path.endsWith(options.workspacePath ?? '')
+        )
+      : workspaces
   ).sort((a, b) => {
     const normA = normalizePath(a.path);
     const normB = normalizePath(b.path);

src/lib/platform.ts

@@ -116,7 +116,5 @@ export function pathsEqual(path1: string, path2: string): boolean {
   const normalize = (p: string) => normalizePath(p).replace(/\\/g, '/');
   const n1 = normalize(path1);
   const n2 = normalize(path2);
-  return process.platform === 'win32'
-    ? n1.toLowerCase() === n2.toLowerCase()
-    : n1 === n2;
+  return process.platform === 'win32' ? n1.toLowerCase() === n2.toLowerCase() : n1 === n2;
 }

tests/unit/storage.test.ts

@@ -199,13 +199,15 @@ describe('readWorkspaceJson', () => {
     expect(result).toBe('/my/workspace.code-workspace');
   });
 
-  it('decodes %20 in workspace', () => {
+  it('decodes percent-encoded characters in workspace URI (e.g. %20, %23, %28, %29)', () => {
     vi.mocked(existsSync).mockReturnValue(true);
     vi.mocked(readFileSync).mockReturnValue(
-      JSON.stringify({ workspace: 'file:///my%20project/ws.code-workspace' })
+      JSON.stringify({
+        workspace: 'file:///path%23with%28hash%29/my%20ws.code-workspace',
+      })
     );
     const result = readWorkspaceJson('/workspace/dir');
-    expect(result).toBe('/my project/ws.code-workspace');
+    expect(result).toBe('/path#with(hash)/my ws.code-workspace');
   });
 
   it('prefers workspace when both folder and workspace exist', () => {
@@ -837,7 +839,7 @@ describe('searchSessions', () => {
   it('returns empty when no matches', async () => {
     vi.mocked(existsSync).mockReturnValue(true);
     vi.mocked(readdirSync).mockReturnValue([]);
-    const result = await searchSessions('xyz', { limit: 10, contextChars: 50 }, '/data');
+    const result = await searchSessions('xyz', { limit: 10 }, '/data');
     expect(result).toEqual([]);
   });
 });