claude-mem 3.3.7 → 3.3.9

package/docs/plans/terminal-effects-integration.md

@@ -0,0 +1,82 @@
+# Terminal Effects Integration Plan
+
+## Overview
+
+Enhance the claude-mem installer with better visual feedback using the existing `@clack/prompts` library (v0.11.0). Focus strictly on improving user experience without adding dependencies or over-engineering.
+
+## Current State Analysis
+
+The installation wizard in `src/commands/install.ts` already uses @clack/prompts with:
+- Basic spinners (`p.spinner()`)
+- Interactive prompts (`p.select()`, `p.confirm()`, `p.text()`)
+- Basic logging (`p.log.info()`, `p.log.warn()`, `p.log.error()`)
+- Group operations (`p.group()`)
+- Intro/outro messaging (`p.intro()`, `p.outro()`)
+
+## Enhancement Targets
+
+### 1. Multi-Step Progress Visualization
+**Current:** Sequential spinners that stop/start individually
+**Enhancement:** Add progress indication for the overall installation flow
+
+### 2. Better Error Display Hierarchy  
+**Current:** Basic error messages mixed with regular output
+**Enhancement:** Consistent error formatting with clear visual separation
+
+### 3. Status Message Improvements
+**Current:** Generic spinner messages
+**Enhancement:** More descriptive, contextual status messages
+
+### 4. Enhanced Verification Feedback
+**Current:** Simple success/failure reporting
+**Enhancement:** Detailed verification with clear visual results
+
+## Technical Approach
+
+### Keep It Simple
+- Use only existing @clack/prompts features
+- No new dependencies
+- No architectural changes
+- Focus on visual polish only
+
+### Minimal Changes Required
+1. Enhance spinner messages with more context
+2. Add step counting to the main installation flow
+3. Improve error message formatting
+4. Add visual separators for better organization
+
+## Implementation Scope
+
+**File to Modify:** `src/commands/install.ts`
+
+**Specific Areas:**
+1. `validatePrerequisites()` - Better progress feedback
+2. `installChromaMcp()` - Enhanced status messages
+3. `p.group()` section - Add step progress indicators
+4. `verifyInstallation()` - Improved results display
+5. Error handling throughout - Consistent formatting
+
+**Not In Scope:**
+- New UI components
+- Complex progress bars (not available in @clack/prompts 0.11.0)  
+- Color customization
+- Animation effects
+- New prompts or interactions
+
+## Success Criteria
+
+1. **Visual Clarity:** Users can easily track installation progress
+2. **Error Visibility:** Problems are clearly highlighted and actionable
+3. **Professional Feel:** Installation feels polished and confident
+4. **Zero Regression:** All existing functionality works exactly the same
+
+## Risk Mitigation
+
+- Changes are cosmetic only - no functional modifications
+- Existing user interactions remain identical
+- Fallback to current behavior if any issues arise
+- Minimal code changes reduce chance of introducing bugs
+
+---
+
+*Following KISS principles: Make what already works look better, don't reinvent anything.*

package/docs/plans/trash-bin-feature-plan.md

@@ -0,0 +1,240 @@
+# Claude-Mem Trash Bin Feature Plan
+
+## Executive Summary
+
+Add a trash bin safety feature to claude-mem that intercepts destructive file operations in Claude Code sessions, replacing permanent deletion with recoverable trash operations. This feature will install trash-cli during setup, configure Claude Code settings to block dangerous rm commands, and provide interactive trash management through the claude-mem CLI.
+
+## Core Objectives
+
+1. **Prevent accidental data loss** by intercepting rm/rm -rf commands in Claude Code sessions
+2. **Provide recovery mechanism** through centralized trash at ~/.claude-mem/trash
+3. **Interactive management** via claude-mem CLI with restore, empty, and view operations
+4. **Seamless integration** with existing claude-mem architecture and installation flow
+
+## Technical Architecture
+
+### Component Overview
+
+```
+claude-mem trash system
+├── Installation Layer
+│   ├── trash-cli npm package installation
+│   ├── Claude Code settings configuration
+│   └── Directory structure creation
+├── Interception Layer
+│   ├── Claude Code permission denials for rm
+│   └── Bash alias recommendations
+├── Storage Layer
+│   ├── ~/.claude-mem/trash/files/
+│   ├── ~/.claude-mem/trash/info/
+│   └── ~/.claude-mem/trash/index.jsonl
+└── Management Layer
+    ├── CLI commands (trash, restore, empty)
+    ├── Interactive prompts (@clack/prompts)
+    └── Trash metadata tracking
+```
+
+### Key Design Decisions
+
+1. **Use sindresorhus/trash-cli** (npm version) for better cross-platform support and faster startup
+2. **Store trash in ~/.claude-mem/trash** to keep all claude-mem data centralized
+3. **Block rm commands via Claude Code permissions** rather than environment aliases
+4. **Follow XDG specification** for trash directory structure
+5. **Maintain operation logs** in ~/.claude-mem/logs for audit trail
+
+## Implementation Strategy
+
+### Phase 1: Core Infrastructure
+
+#### Installation Enhancement
+- Extend `src/commands/install.ts` to include trash-cli installation
+- Add trash directory to `ensureDirectoryStructure()`
+- Update Claude Code settings with rm command denials
+
+#### Directory Structure
+```
+~/.claude-mem/trash/
+├── files/           # Actual trashed files
+├── info/           # Metadata (.trashinfo files)
+└── index.jsonl     # claude-mem specific tracking
+```
+
+### Phase 2: CLI Commands
+
+#### New Commands Structure
+```
+claude-mem trash                # Interactive trash management
+claude-mem trash list           # List trashed items
+claude-mem trash restore <file> # Restore specific file
+claude-mem trash empty          # Empty trash (with confirmation)
+claude-mem trash stats          # Show trash statistics
+```
+
+#### Interactive Flow
+Using @clack/prompts for consistency:
+1. Main menu: List, Restore, Empty, Stats, Exit
+2. List view: Shows files with deletion date, original path, size
+3. Restore: Multi-select interface for batch restoration
+4. Empty: Progressive confirmation (show what will be deleted)
+
+### Phase 3: Safety Configuration
+
+#### Claude Code Settings Modification
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(rm *)",
+      "Bash(rm -rf *)",
+      "Bash(rm -r *)",
+      "Bash(sudo rm *)"
+    ],
+    "allowedTools": [
+      "Bash(trash *)"
+    ]
+  }
+}
+```
+
+#### Shell Configuration (Optional)
+Provide recommendations for user's shell profile:
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+alias rm='echo "Use trash command instead (or \\rm for bypass)" && false'
+alias del='trash'
+```
+
+## File System Operations
+
+### Trash Operation Flow
+1. **File deletion intercepted** → trash-cli moves to ~/.claude-mem/trash
+2. **Metadata recorded** → .trashinfo file created with original path, deletion time
+3. **Index updated** → claude-mem tracks in index.jsonl for fast queries
+4. **Log entry created** → Operation logged to ~/.claude-mem/logs
+
+### Restore Operation Flow
+1. **User selects file(s)** → Interactive prompt or direct command
+2. **Validate restoration path** → Check if original location exists
+3. **Move file back** → From trash to original location
+4. **Update index** → Remove from trash index
+5. **Log operation** → Record restoration in logs
+
+## User Experience
+
+### Installation Experience
+```
+┌  Claude-Mem Installation
+│
+◆  Installing core components...
+│  ✔ Created directory structure
+│  ✔ Installed trash-cli safety system
+│  ✔ Configured Claude Code settings
+│  ✔ Added rm command protection
+│
+◇  Trash bin configured at ~/.claude-mem/trash
+│  Use 'claude-mem trash' to manage deleted files
+│
+└  Installation complete!
+```
+
+### Trash Management Experience
+```
+┌  Claude-Mem Trash Manager
+│
+◆  What would you like to do?
+│  ○ List trashed items (3 files)
+│  ○ Restore files
+│  ○ Empty trash
+│  ○ View statistics
+│  ○ Exit
+│
+└
+```
+
+## Error Handling
+
+### Graceful Degradation
+1. If trash-cli installation fails → Warn user, continue installation
+2. If Claude Code settings update fails → Log warning, provide manual instructions
+3. If trash directory creation fails → Fall back to system trash location
+
+### Recovery Mechanisms
+- Manual bypass: Users can use `\rm` to bypass alias if needed
+- Restore from backup: Keep 24-hour backup of trash index
+- Conflict resolution: If restore path exists, prompt for new location
+
+## Integration Points
+
+### With Existing claude-mem Systems
+1. **Logger**: Use existing FileLogger for all operations
+2. **PathResolver**: Extend with `getTrashDir()`, `getTrashInfoDir()`
+3. **Settings**: Add trash preferences to Settings interface
+4. **CLI Structure**: Follow established command patterns
+
+### With Claude Code
+1. **Settings.json**: Modify permissions on installation
+2. **Hooks**: Consider pre-delete hook for future enhancement
+3. **MCP Server**: Potential future integration for trash queries
+
+## Success Metrics
+
+1. **Zero data loss** from accidental rm commands in Claude Code
+2. **<100ms** trash operation latency
+3. **95% recovery success rate** for trashed files
+4. **<1% storage overhead** from metadata
+
+## Security Considerations
+
+1. **Path validation** to prevent directory traversal
+2. **Permission preservation** when restoring files
+3. **Size limits** to prevent trash from filling disk
+4. **Age-based cleanup** option (30-day default)
+
+## Future Enhancements
+
+1. **Smart recovery suggestions** based on file patterns
+2. **Integration with claude-mem memories** for tracking deleted code
+3. **Undo stack** for recent operations
+4. **Cloud backup** integration for critical files
+5. **Project-specific trash** for better organization
+
+## Dependencies
+
+- **trash-cli** (npm): Core trash functionality
+- **@clack/prompts**: Interactive CLI (existing)
+- **commander**: CLI framework (existing)
+- No additional dependencies required
+
+## Testing Strategy
+
+1. **Unit tests** for trash operations
+2. **Integration tests** with Claude Code settings
+3. **Cross-platform testing** (macOS, Linux, Windows)
+4. **Recovery scenarios** testing
+
+## Documentation Updates
+
+1. Update README with trash feature description
+2. Add trash commands to CLI help
+3. Create troubleshooting guide for common issues
+4. Add configuration examples to documentation
+
+## Risk Mitigation
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| trash-cli installation fails | Medium | Graceful degradation, manual instructions |
+| Claude Code ignores settings | High | Test thoroughly, provide workarounds |
+| Disk space issues | Medium | Size limits, age-based cleanup |
+| Performance impact | Low | Lazy loading, indexed operations |
+| User confusion | Low | Clear documentation, intuitive UI |
+
+## Implementation Timeline
+
+- **Week 1**: Core infrastructure and installation integration
+- **Week 2**: CLI commands and interactive interface
+- **Week 3**: Testing, documentation, and release
+
+## Conclusion
+
+This trash bin feature provides essential safety for Claude Code users while maintaining the simplicity and efficiency that claude-mem is known for. By following existing architectural patterns and using proven tools, we can deliver a robust solution that prevents data loss without adding complexity to the user experience.

package/docs/plans/trash-bin-minimal-plan.md

@@ -0,0 +1,102 @@
+# Claude-Mem Trash Bin - Minimal Implementation Plan
+
+## Core Truth
+Make a trash command that moves files to ~/.claude-mem/trash. Make a restore command that moves them back. Ship it. Fix what breaks.
+
+## The ONE Thing That Matters
+Prevent permanent data loss when Claude Code deletes files. Everything else is noise.
+
+## Implementation (Make It Work First)
+
+### Step 1: Basic Trash Command
+```typescript
+// src/commands/trash.ts
+export async function trash(filePath: string) {
+  const trashDir = join(homedir(), '.claude-mem', 'trash');
+  if (!existsSync(trashDir)) mkdirSync(trashDir, { recursive: true });
+  
+  const fileName = basename(filePath);
+  const destination = join(trashDir, fileName);
+  renameSync(filePath, destination);
+  
+  console.log(`Moved ${fileName} to trash`);
+}
+```
+
+### Step 2: Basic Restore Command  
+```typescript
+// src/commands/restore.ts
+export async function restore() {
+  const trashDir = join(homedir(), '.claude-mem', 'trash');
+  const files = readdirSync(trashDir);
+  
+  if (files.length === 0) {
+    console.log('Trash is empty');
+    return;
+  }
+  
+  // Use existing clack prompts - we already have it
+  const file = await p.select({
+    message: 'Select file to restore:',
+    options: files.map(f => ({ value: f, label: f }))
+  });
+  
+  renameSync(join(trashDir, file), join(process.cwd(), file));
+  console.log(`Restored ${file}`);
+}
+```
+
+### Step 3: Add to CLI
+```typescript
+// src/bin/cli.ts
+program.command('trash <file>').action(trash);
+program.command('restore').action(restore);
+```
+
+### Step 4: Update Install (Optional)
+During install, show:
+```
+💡 Tip: Use 'claude-mem trash <file>' instead of rm for safe deletion
+```
+
+## That's It. Ship It.
+
+## What We DON'T Do (Yet)
+
+❌ NO trash-cli installation - use native fs operations
+❌ NO Claude Code settings modification - let users discover the need
+❌ NO metadata tracking - filename is enough to start
+❌ NO original path storage - restore to current directory
+❌ NO conflict resolution - let it fail naturally
+❌ NO size limits - fix when someone's disk fills
+❌ NO age cleanup - fix when someone complains
+❌ NO shell aliases - users can add if they want
+❌ NO permissions validation - fs.rename will fail if not allowed
+❌ NO XDG compliance - our own directory is simpler
+
+## When to Add Features
+
+Only add when these ACTUALLY happen:
+1. **Filename collision** → Add timestamp suffix
+2. **Users can't find files** → Add list command  
+3. **Need original location** → Add simple JSON tracking
+4. **Trash gets huge** → Add empty command
+5. **Users forget about trash** → Add install tip
+
+## Success Metric
+
+One user successfully recovers one accidentally deleted file. That's it.
+
+## Timeline
+
+Day 1: Write the 20 lines of code above
+Day 2: Test it, ship it
+Day 3: Wait for real feedback
+
+## The Test
+
+Can someone understand what this does in 5 seconds? 
+- `claude-mem trash file.txt` → Moves file to trash
+- `claude-mem restore` → Brings it back
+
+YES. Ship it.