claude-mem 3.3.7 → 3.3.9

package/docs/todos/trash-bin-implementation-todos.md

@@ -0,0 +1,348 @@
+# Claude-Mem Trash Bin Implementation TODOs
+
+## Phase 1: Core Infrastructure Setup
+
+### 1.1 Extend PathResolver Utility
+- [ ] Add `getTrashDir()` method to return `~/.claude-mem/trash`
+- [ ] Add `getTrashFilesDir()` method for `~/.claude-mem/trash/files`
+- [ ] Add `getTrashInfoDir()` method for `~/.claude-mem/trash/info`
+- [ ] Add `getTrashIndexPath()` method for `~/.claude-mem/trash/index.jsonl`
+- [ ] Update `src/shared/paths.ts` with new path methods
+
+### 1.2 Extend Settings Interface
+- [ ] Add `trashEnabled: boolean` field to Settings interface
+- [ ] Add `trashMaxSize: number` field for size limit (default 1GB)
+- [ ] Add `trashMaxAge: number` field for auto-cleanup (default 30 days)
+- [ ] Add `trashAutoCleanup: boolean` field
+- [ ] Update `src/shared/types.ts` with new settings fields
+
+### 1.3 Create Trash Types
+- [ ] Create `TrashItem` interface with fields:
+  - `id: string`
+  - `originalPath: string`
+  - `trashedPath: string`
+  - `deletionDate: Date`
+  - `size: number`
+  - `restorable: boolean`
+- [ ] Create `TrashMetadata` interface for .trashinfo files
+- [ ] Create `TrashStats` interface for statistics
+- [ ] Add types to `src/shared/types.ts`
+
+## Phase 2: Installation Integration
+
+### 2.1 Modify install.ts Core Functions
+- [ ] Create `installTrashCli()` function:
+  - [ ] Try npm install first
+  - [ ] Fallback to pip install
+  - [ ] Handle installation failures gracefully
+  - [ ] Return installation status
+- [ ] Update `ensureDirectoryStructure()`:
+  - [ ] Add trash directory creation
+  - [ ] Create files/ subdirectory
+  - [ ] Create info/ subdirectory
+  - [ ] Initialize index.jsonl file
+- [ ] Create `configureTrashSafety()` function:
+  - [ ] Read existing Claude Code settings
+  - [ ] Add rm command denials to permissions
+  - [ ] Add trash command to allowed tools
+  - [ ] Write updated settings
+
+### 2.2 Update Installation Flow
+- [ ] Add trash installation to `p.group()` in main install flow
+- [ ] Add trash configuration step after hooks configuration
+- [ ] Update progress messages to include trash setup
+- [ ] Add trash status to installation summary
+- [ ] Handle partial installation failures
+
+### 2.3 Create Uninstall Support
+- [ ] Add trash cleanup option to uninstall command
+- [ ] Prompt user about keeping/removing trashed files
+- [ ] Remove trash directories if requested
+- [ ] Clean up Claude Code settings modifications
+- [ ] Update `src/commands/uninstall.ts`
+
+## Phase 3: CLI Commands Implementation
+
+### 3.1 Create Main Trash Command
+- [ ] Create `src/commands/trash.ts` file
+- [ ] Implement main `trash()` function with options
+- [ ] Add interactive menu using @clack/prompts:
+  - [ ] List trashed items
+  - [ ] Restore files
+  - [ ] Empty trash
+  - [ ] Show statistics
+  - [ ] Exit option
+- [ ] Handle command-line arguments for direct operations
+- [ ] Add error handling and logging
+
+### 3.2 Implement List Functionality
+- [ ] Create `listTrashedItems()` function
+- [ ] Read and parse trash index.jsonl
+- [ ] Format output with:
+  - [ ] File name
+  - [ ] Original path
+  - [ ] Deletion date (relative time)
+  - [ ] File size (human readable)
+- [ ] Add sorting options (date, size, name)
+- [ ] Implement pagination for large lists
+
+### 3.3 Implement Restore Functionality
+- [ ] Create `restoreFiles()` function
+- [ ] Add interactive file selection (multi-select)
+- [ ] Validate restoration paths
+- [ ] Handle path conflicts:
+  - [ ] Prompt for new location
+  - [ ] Option to overwrite
+  - [ ] Option to rename
+- [ ] Move files from trash to original location
+- [ ] Update trash index
+- [ ] Log restoration operations
+
+### 3.4 Implement Empty Trash
+- [ ] Create `emptyTrash()` function
+- [ ] Show summary of what will be deleted
+- [ ] Add progressive confirmation:
+  - [ ] First confirm action
+  - [ ] Show file count and total size
+  - [ ] Final confirmation with typing requirement
+- [ ] Delete files from trash/files
+- [ ] Clean up .trashinfo files
+- [ ] Clear index.jsonl
+- [ ] Log empty operation
+
+### 3.5 Implement Statistics
+- [ ] Create `showTrashStats()` function
+- [ ] Calculate and display:
+  - [ ] Total items in trash
+  - [ ] Total size used
+  - [ ] Oldest item date
+  - [ ] Most recent deletion
+  - [ ] File type breakdown
+- [ ] Add storage usage percentage
+- [ ] Show auto-cleanup status if enabled
+
+### 3.6 Add CLI Registration
+- [ ] Update `src/bin/cli.ts`:
+  - [ ] Import trash command
+  - [ ] Add `.command('trash [action]')`
+  - [ ] Add `.description()` for trash command
+  - [ ] Add options for list, restore, empty, stats
+  - [ ] Register action handler
+
+## Phase 4: Trash Operations Core
+
+### 4.1 Create Trash Service
+- [ ] Create `src/services/trash-service.ts`
+- [ ] Implement `moveToTrash(filePath: string)` method
+- [ ] Implement `restoreFromTrash(trashId: string)` method
+- [ ] Implement `getTrashContents()` method
+- [ ] Implement `emptyTrashCompletely()` method
+- [ ] Add index management methods
+
+### 4.2 Implement Metadata Management
+- [ ] Create `.trashinfo` file generator
+- [ ] Follow freedesktop.org trash specification:
+  ```ini
+  [Trash Info]
+  Path=/original/file/path
+  DeletionDate=2024-01-15T10:30:00
+  ```
+- [ ] Create metadata parser
+- [ ] Add metadata validation
+- [ ] Handle corrupted metadata gracefully
+
+### 4.3 Create Index Management
+- [ ] Implement `addToTrashIndex()` method
+- [ ] Implement `removeFromTrashIndex()` method
+- [ ] Implement `searchTrashIndex()` method
+- [ ] Add index compaction for performance
+- [ ] Handle concurrent access safely
+
+## Phase 5: Claude Code Integration
+
+### 5.1 Settings Configuration
+- [ ] Create `updateClaudeSettings()` function
+- [ ] Read `~/.claude/settings.json`
+- [ ] Add permissions.deny array:
+  ```json
+  [
+    "Bash(rm *)",
+    "Bash(rm -rf *)",
+    "Bash(rm -r *)",
+    "Bash(sudo rm *)"
+  ]
+  ```
+- [ ] Add to permissions.allowedTools:
+  ```json
+  ["Bash(trash *)"]
+  ```
+- [ ] Handle missing settings file
+- [ ] Preserve existing user settings
+
+### 5.2 Create Shell Configuration Helper
+- [ ] Generate shell alias recommendations
+- [ ] Detect user's shell (bash, zsh, fish)
+- [ ] Provide copy-paste ready configurations
+- [ ] Create `claude-mem configure-shell` subcommand
+- [ ] Add to documentation
+
+## Phase 6: Safety and Error Handling
+
+### 6.1 Path Validation
+- [ ] Implement `validatePath()` function
+- [ ] Prevent directory traversal attacks
+- [ ] Check for symbolic links
+- [ ] Validate file permissions
+- [ ] Handle special characters in filenames
+
+### 6.2 Graceful Degradation
+- [ ] Handle trash-cli not installed
+- [ ] Fallback to system trash if custom fails
+- [ ] Provide manual recovery instructions
+- [ ] Log all failures for debugging
+- [ ] Add retry mechanisms for transient failures
+
+### 6.3 Conflict Resolution
+- [ ] Implement `resolvePathConflict()` function
+- [ ] Offer rename suggestions
+- [ ] Allow custom path selection
+- [ ] Create backup before overwrite
+- [ ] Log all conflict resolutions
+
+## Phase 7: Auto-Cleanup Features
+
+### 7.1 Size-Based Cleanup
+- [ ] Monitor trash directory size
+- [ ] Implement `checkTrashSize()` function
+- [ ] Warn when approaching limit
+- [ ] Auto-delete oldest items if enabled
+- [ ] Keep important files (marked/starred)
+
+### 7.2 Age-Based Cleanup
+- [ ] Implement `cleanOldTrashItems()` function
+- [ ] Check file ages daily
+- [ ] Delete items older than threshold
+- [ ] Skip items marked as keep-forever
+- [ ] Log cleanup operations
+
+### 7.3 Cleanup Scheduler
+- [ ] Create background cleanup check
+- [ ] Run on claude-mem startup
+- [ ] Add manual trigger option
+- [ ] Show cleanup in progress
+- [ ] Report cleanup results
+
+## Phase 8: Testing
+
+### 8.1 Unit Tests
+- [ ] Test trash service methods
+- [ ] Test path validation
+- [ ] Test metadata management
+- [ ] Test index operations
+- [ ] Test conflict resolution
+
+### 8.2 Integration Tests
+- [ ] Test installation flow with trash
+- [ ] Test Claude Code settings modification
+- [ ] Test trash-cli integration
+- [ ] Test full trash lifecycle
+- [ ] Test error recovery
+
+### 8.3 Cross-Platform Tests
+- [ ] Test on macOS
+- [ ] Test on Ubuntu Linux
+- [ ] Test on Windows (WSL)
+- [ ] Test with different shells
+- [ ] Test permission edge cases
+
+## Phase 9: Documentation
+
+### 9.1 Update README
+- [ ] Add trash feature description
+- [ ] Include installation requirements
+- [ ] Add usage examples
+- [ ] Document configuration options
+- [ ] Add troubleshooting section
+
+### 9.2 Create Trash Guide
+- [ ] Write comprehensive trash documentation
+- [ ] Include command examples
+- [ ] Add recovery scenarios
+- [ ] Document best practices
+- [ ] Create FAQ section
+
+### 9.3 Update CLI Help
+- [ ] Add trash command help text
+- [ ] Include all subcommands
+- [ ] Add usage examples
+- [ ] Document options and flags
+- [ ] Update man page if exists
+
+## Phase 10: Performance Optimization
+
+### 10.1 Index Optimization
+- [ ] Implement lazy loading for trash index
+- [ ] Add caching for frequent queries
+- [ ] Use binary search for sorted data
+- [ ] Implement index compaction
+- [ ] Add performance metrics
+
+### 10.2 File Operations
+- [ ] Batch file operations when possible
+- [ ] Use async I/O for large files
+- [ ] Implement progress indicators
+- [ ] Add operation cancellation
+- [ ] Optimize directory scanning
+
+## Phase 11: User Experience Polish
+
+### 11.1 Interactive Improvements
+- [ ] Add colorized output
+- [ ] Implement fuzzy search for restore
+- [ ] Add file preview option
+- [ ] Show file type icons
+- [ ] Add confirmation sounds (optional)
+
+### 11.2 Status Reporting
+- [ ] Create detailed progress bars
+- [ ] Add operation time estimates
+- [ ] Show transfer speeds
+- [ ] Display space saved
+- [ ] Add success animations
+
+## Phase 12: Future Enhancements (Post-MVP)
+
+### 12.1 Advanced Features
+- [ ] Implement trash versioning
+- [ ] Add trash compression
+- [ ] Create trash export/import
+- [ ] Add cloud backup integration
+- [ ] Implement smart suggestions
+
+### 12.2 Integration Extensions
+- [ ] VSCode extension integration
+- [ ] Git integration for tracked files
+- [ ] Project-specific trash bins
+- [ ] Team trash sharing (cloud service)
+- [ ] Webhook notifications
+
+## Completion Checklist
+
+### Before Release
+- [ ] All core features implemented
+- [ ] Tests passing (>90% coverage)
+- [ ] Documentation complete
+- [ ] Cross-platform verified
+- [ ] Performance benchmarked
+- [ ] Security review completed
+- [ ] User feedback incorporated
+- [ ] Version bump prepared
+- [ ] Release notes written
+- [ ] npm package updated
+
+### Post-Release
+- [ ] Monitor error reports
+- [ ] Gather user feedback
+- [ ] Plan next iteration
+- [ ] Update roadmap
+- [ ] Celebrate! 🎉

package/docs/todos/trash-bin-minimal-todos.md

@@ -0,0 +1,27 @@
+# Claude-Mem Trash - Minimal TODOs
+
+## Make It Work (Day 1)
+
+### Create Basic Commands
+- [ ] Create `src/commands/trash.ts` with 10-line implementation
+- [ ] Create `src/commands/restore.ts` with 15-line implementation  
+- [ ] Add both commands to `src/bin/cli.ts`
+- [ ] Test moving a file to trash and restoring it
+- [ ] Ship it
+
+## Fix What Actually Breaks (When It Breaks)
+
+### Only If Users Report Issues
+- [ ] IF files collide → Add timestamp to filename
+- [ ] IF users need a list → Add `trash list` command
+- [ ] IF restore location matters → Store original path in `${file}.json`
+- [ ] IF trash fills disk → Add `trash empty` command
+- [ ] IF users want rm protection → Document alias setup
+
+## That's All
+
+No more todos until real problems surface from real usage.
+
+Total lines of code to write: ~30
+Total time to implement: 2 hours
+Total features that might never be needed: 0

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "claude-mem",
-  "version": "3.3.7",
+  "version": "3.3.9",
   "description": "Memory compression system for Claude Code - persist context across sessions",
+  "type": "module",
+  "main": "claude-mem",
+  "scripts": {
+    "dev": "tsx src/bin/cli.ts",
+    "dev:install": "node dist/cli.js install --force",
+    "dev:status": "node dist/cli.js status",
+    "dev:compress": "node dist/cli.js compress",
+    "dev:load": "node dist/cli.js load-context",
+    "dev:uninstall": "node dist/cli.js uninstall",
+    "build": "tsc",
+    "test:watch": "npm test -- --watch",
+    "lint": "eslint 'src/**/*.ts' 'hooks/**/*.ts' 'test/**/*.ts'",
+    "lint:fix": "npm run lint -- --fix",
+    "format": "prettier --write 'src/**/*.ts' 'hooks/**/*.ts' 'test/**/*.ts'",
+    "build:multiplatform": "./scripts/build-multiplatform.sh",
+    "publish": "./scripts/npm-publish.sh && cd releases/npm-package && npm publish",
+    "publish:latest": "npm version patch && ./scripts/npm-publish.sh && cd releases/npm-package && npm publish"
+  },
   "keywords": [
     "claude",
     "claude-code",
@@ -10,7 +28,9 @@
     "compression",
     "knowledge-graph",
     "transcript",
-    "cli"
+    "cli",
+    "typescript",
+    "bun"
   ],
   "author": "Alex Newman",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,13 +46,43 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "dependencies": {
+    "@anthropic-ai/claude-code": "^1.0.88",
+    "@clack/prompts": "^0.11.0",
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "boxen": "^8.0.1",
+    "chalk": "^5.6.0",
+    "commander": "^14.0.0",
+    "figlet": "^1.8.2",
+    "glob": "^11.0.3",
+    "gradient-string": "^3.0.0",
+    "handlebars": "^4.7.8",
+    "oh-my-logo": "^0.3.2"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.0",
+    "@types/figlet": "^1.7.0",
+    "@types/handlebars": "^4.0.40",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "chai": "^4.3.0",
+    "eslint": "^8.0.0",
+    "prettier": "^3.0.0",
+    "ts-node": "^10.0.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  },
   "bin": {
-    "claude-mem": "./claude-mem"
+    "claude-mem": "dist/bin/cli.js"
   },
   "files": [
-    "claude-mem",
-    "hooks",
     "dist",
-    ".mcp.json"
+    "hooks",
+    "docs"
   ]
 }